project-context-bootstrap

Project Context Bootstrap

Create a compact, durable working model of a repo before the agent starts inventing one from guesswork.

Goal

Turn a repo with weak or missing agent-facing context into a repo with:

• a clear stack and structure summary;
• known commands and verification paths;
• durable context files or notes with real content;
• explicit approval before reorganizing existing docs.

Workflow

1. Detect
   • inspect project manifests, lockfiles, workspace layout, test commands, and major directories;
   • detect whether context already exists: AGENTS.md, docs/ai/, runbooks, plans, or other agent-facing docs.
2. Study existing context first
   • if the repo already has useful docs, read them before proposing replacements;
   • separate what looks good, stale, missing, or conflicting.
3. Ask
   • have a real project-discovery conversation with the user;
   • cover what the product is, who uses it, main features, risky areas, workflow conventions, and external dependencies;
   • follow up until the project is actually understandable.
4. Summarize
   • restate your understanding in concise project language;
   • confirm accuracy before writing or reorganizing context.
5. Propose
   • suggest the smallest useful context structure:
     • top-level AGENTS.md or compact startup doc;
     • docs/ai/architecture.md;
     • docs/ai/how-to-test.md;
     • task-specific notes only if needed;
   • ask before reorganizing or overwriting anything durable.
6. Populate
   • write real content from code and user input, not placeholders;
   • include concrete commands, file paths, key modules, and current conventions.
7. Validate
   • verify the new context is small, accurate, and actually useful for the next session.

Existing Repo Rules

• Preserve good context; do not replace it with generic scans.
• Show what you want to keep, improve, and add before changing layout.
• Never silently move or delete user-written docs.

Compression Rules