Context Engineering

Overview

Create a consistent project context structure (team navigation + project folder) and link it to a code directory. Default target root is ~/clawDir/team, but allow the user to specify another root path.

Loading Model (L1/L2/L3)

• L1: Project skill.md — global overview, module navigation, environment notes.
• L2: modules/ + agents/ — task-scoped module docs and agent role docs. Load the module overview first, then specific submodules; load the relevant agent README when working on that role’s tasks.
• L3: references/ — entrypoints, API indices, migrations, evidence-level docs.

Workflow

1. Collect inputs

   • project_name (folder name)
   • code_dir (absolute path to the code)
   • target_root (optional). If not provided, use ~/clawDir/team.

2. Analyze the code structure

   • Identify tech stack and main areas (frontend/backend/qa/etc.) from code directory structure and key files.
   • Read top-level docs: README*, docs/, tech.md, architecture.md, CHANGELOG* if present.

3. Initialize the context structure

   • Prefer running the bundled script:

     python scripts/init_context_project.py \
       --project <project_name> \
       --code-dir <code_dir> \
       --target-root <target_root>
     

   • The script infers module buckets from the codebase and creates module folders dynamically.
   • The script is idempotent: it won’t overwrite existing files.

4. Populate content (critical)

   • Fill skill.md (L1) with project summary, architecture, entrypoints, build/run, module navigation.
   • Fill modules/<module>/README.md (overview) and modules/<module>/<module>.md (detail).
   • Fill references/entrypoints.md with code-level entrypoints and indexes.

5. Post-init checks

   • Verify the created files exist and are filled under: <target_root>/projects/<project_name>/.
   • If the user wants custom content, update modules and references accordingly.
   • Record major changes in decisions.md (project-level) or decisions.jsonl (agent-level).

Modules Directory Guidance

• modules/ is generated based on the target codebase (not fixed).
• Recommended buckets: frontend, backend, qa, reviewer (only if inferred).
• Each module may contain multiple detailed docs; keep an overview modules/<module>/README.md and a modules/<module>/<module>.md for detailed module notes.
• If a domain is present (e.g., mobile, data, ops, infra), create that module.

Generation Rules (Modules & Agents)

Modules

• Each module folder must include:
  • modules/<module>/README.md (overview)
  • modules/<module>/<module>.md (details: Scope, Key Responsibilities, Important Notes, Interfaces & Dependencies)
• If a module is large, split into multiple files (e.g., A.md, B.md, C.md). In that case, <module>.md becomes an index/summary that describes each sub-file and when to load it.

Agents

• Create one folder per agent under agents/<agent>/.
• Agent list is inferred from module buckets; always include reviewer.
• Each agent folder must include:
  • README.md with Role, Principles, Responsibilities, Deliverables, Working Style, Notes
  • tools.md (Markdown)
  • memory.md (Markdown)
  • decisions.jsonl (JSONL, one decision per line)
  • fails.jsonl (JSONL, one failure per line)
• README.md must also include a brief description of the purpose of other files in the current agent directory.

Content Extraction Rules (General)

Keep SKILL.md lean. For detailed extraction guidance (entrypoints, flows, data, tests, i18n), load:

• references/extraction-rules.md

Output Templates (Required)

L1 (skill.md)

• Project summary (what it is + target users)
• Architecture & boundaries
• Entrypoints + build/run
• Module navigation
• Progressive loading model (L1/L2/L3)
• Spec-driven development
  • Spec-first rule (no implementation without a spec)
  • Spec template (scope, interfaces, edge cases/errors, acceptance criteria, tests)
  • Change control (spec updates recorded in decisions)
  • Traceability (code/tests map back to spec items)

L2 (modules//README.md)

• Responsibilities
• Key areas/files
• Typical tasks

L2 (modules//.md)

• Scope
• Key Responsibilities
• Important Notes (constraints, risks, decisions)
• Interfaces & Dependencies
• Key flows (if applicable)
• Testing/QA hooks

L2 (agents//README.md)

• Role
• Principles
• Responsibilities
• Deliverables
• Working Style
• Notes
• Description of other files in the agent directory

L3 (references/entrypoints.md)

• Entry file index
• Core logic/index files
• Data/storage index
• i18n index
• Build/release/ops entrypoints

Quality Checklist (Before Finalizing)

• L1 filled with accurate architecture and run/build info
• Each module has README + .md
• References contain concrete file paths
• Loading paths cover UI/UX, core logic, QA, release scenarios
• Agent folders exist with clear responsibilities

Files Created

• <target_root>/readme.md (if missing)
• <target_root>/projects/projects.md (index with new project entry)
• <target_root>/projects/<project_name>/readme.md
• <target_root>/projects/<project_name>/goals.md
• <target_root>/projects/<project_name>/skill.md
• <target_root>/projects/<project_name>/project_status.md
• <target_root>/projects/<project_name>/decisions.md
• <target_root>/projects/<project_name>/agents/agents.md
• <target_root>/projects/<project_name>/modules/README.md
• <target_root>/projects/<project_name>/modules/<module>/README.md (modules inferred from code)
• <target_root>/projects/<project_name>/modules/<module>/<module>.md
• <target_root>/projects/<project_name>/references/entrypoints.md

Resources

• scripts/init_context_project.py — scaffold generator (preferred).