agent-method 1.5.0

package/templates/entry-points/CLAUDE.md

@@ -0,0 +1,109 @@
+# {Project Name} — Agent Entry Point
+
+<!-- INSTRUCTION: Replace {Project Name} and write a 1-2 sentence project description below -->
+{Describe what your project does, its architecture, and key technologies.}
+
+## On every query
+
+1. This file is auto-loaded — read it first
+2. Read `STATE.md` for current position, decisions, blockers
+3. Scope based on query type (see table below)
+
+## Scoping rules
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
+| **Context refresh** | .context/ (all), project structure | .context/, this file (if scoping rules affected) |
+| **{your-domain-type}** | .context/BASE.md + .context/{SPECIALIST}.md | {affected working files} |
+| **Methodology guidance** | .context/METHODOLOGY.md | -- |
+| **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
+| **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+
+<!-- INSTRUCTION: Replace the {your-domain-type} row with project-specific query types.
+     Each should pair .context/BASE.md with one specialist. Add as many rows as needed. -->
+
+## Dependency cascade
+
+When a file changes, check this table and update dependent files in the same response.
+
+| When this changes | Also update |
+|------------------|-------------|
+| Phase completion | SUMMARY.md (add entry), STATE.md (update position), ROADMAP.md (mark done) |
+| Requirements change | REQUIREMENTS.md, ROADMAP.md, PLAN.md (if current task affected) |
+| New decision made | STATE.md (decisions table — record immediately, never defer) |
+| Open question resolved | STATE.md (mark resolved with resolution text, don't delete) |
+| Project structure | .context/BASE.md (codebase map), this file (if new query types needed) |
+| Intelligence layer file exceeds 300 lines | Restructure into index + components subdirectory (keep active content, archive completed sections) |
+| New domain area | .context/BASE.md, consider new .context/ specialist, this file (if new scoping row) |
+| Session close | SESSION-LOG.md (append micro-entry — workflow, features, cascades, friction, findings) |
+
+<!-- INSTRUCTION: Add project-specific cascade rules below the universal ones above. -->
+
+## Workflow
+
+Select based on query type:
+- **General task** — Review, Plan, Implement, Document, Update
+- **Code change** — Review, Plan, Implement, Context-sync, Update
+- **Context refresh** — Scan, Compare, Update-context, Cascade, Record
+- **First session** — Detect, Initialize, Map, Pair, Ready
+
+## Interaction level
+
+mode: checkpoint
+<!-- autonomous | checkpoint | collaborative | supervised -->
+<!-- checkpoint: propose plan, wait for approval, report at completion (default) -->
+
+## Model tier
+
+tier: standard
+<!-- lite | standard | full -->
+<!-- lite: minimal rules, STATE.md only, 2 cascade rules — for Haiku or simple projects -->
+<!-- standard: core rules + context pairing, overflow to .context/METHODOLOGY.md — for Sonnet (default) -->
+<!-- full: all rules in entry point, all intelligence layer files — for Opus or complex projects -->
+
+## Method version
+
+method_version: 1.5
+<!-- Tracks which methodology version generated this entry point -->
+<!-- Use `agent-method status` to compare against latest -->
+
+## CLI tools (optional)
+
+Available via `npx agent-method` (zero-install) or `pip install agent-method-tools`:
+
+| When you want to... | Run |
+|---------------------|-----|
+| Validate this entry point | `agent-method check` |
+| See what type of project this is | `agent-method scan` |
+| Test how a query routes | `agent-method route "your question"` |
+| Extract a refinement report | `agent-method refine` |
+| Check methodology version | `agent-method status` |
+| Update methodology files | `agent-method upgrade` |
+| See what an entry point should contain | `agent-method init code` / `context` / `data` / `mix` |
+
+<!-- INSTRUCTION: The agent can suggest these commands when the user asks about validation,
+     project setup, or methodology updates. All commands auto-detect project type and find
+     entry points automatically. Add --json for machine-readable output. -->
+
+## Conventions
+
+- Record decisions in STATE.md in the SAME response as the work — never defer
+- Load .context/BASE.md + one specialist per query — never all context files
+- After every file change, check the cascade table — deferred cascades don't happen
+- Every code change is also a context change — update the codebase map
+- Surface uncertainty as open questions in STATE.md — never guess silently
+- Keep intelligence layer files under 300 lines — split into index + components subdirectory when exceeded
+- Propose plans and wait for approval — the human controls direction
+- At session close, append a micro-entry to SESSION-LOG.md — never skip, never read previous entries during normal work
+
+## Do not
+
+- Modify project source code, tests, or pre-existing documentation through methodology operations — only create/modify methodology files (STATE.md, .context/, PLAN.md, etc.)
+- Delete existing project files during brownfield integration — methodology is additive only
+- Load files not in the scoping table's read-set for the current query type
+- Defer STATE.md decision recording to end of session
+- Skip cascade checks after file changes
+- Load multiple specialist .context/ files for a single query
+
+<!-- INSTRUCTION: Add project-specific "do not" rules as you discover common mistakes -->

package/templates/extensions/MANIFEST.md

@@ -0,0 +1,110 @@
+# Extension Manifest
+
+How project-type extensions compose into entry points. This document defines compatibility, merging rules, and the composition algorithm.
+
+## Available extensions
+
+| Extension | File | Project types | Workflows | Query patterns added |
+|-----------|------|--------------|-----------|---------------------|
+| **code-project** | code-project.md | code, mixed | WF-02 | 6 (code_change, bug_fix, dependency_update, database_work, api_work, deployment_work) |
+| **data-exploration** | data-exploration.md | data, mixed | WF-05 | 9 (data_ingest, schema_query, explore_entity, relationship_query, quality_check, analytical_query, document_search, dimension_management, add_reference) |
+| **analytical-system** | analytical-system.md | analytical, mixed | WF-06 | 4 (chain_work, evaluation, composition, domain_research) |
+
+## Compatibility matrix
+
+Extensions are additive. Any combination is valid — they add rows to different sections without conflict.
+
+| Combination | Compatible | Notes |
+|-------------|:----------:|-------|
+| code + data | yes | Common for data-backed applications. Both sets of scoping rules active. |
+| code + analytical | yes | Common for ML/AI applications with code and prompt pipelines. |
+| data + analytical | yes | Common for data analysis with evaluation pipelines. |
+| code + data + analytical | yes | Full mixed project. All scoping rules active. |
+| any + general | yes | General is the base — extensions add to it. |
+
+## Composition algorithm
+
+When setup.sh (or manual composition) applies extensions, it follows this algorithm:
+
+### Step 1: Start with the base entry point
+
+The base entry point (from starter or full template) provides:
+- Universal scoping rules (planning, context refresh, phase completion, backlog)
+- Universal cascade rules (phase completion, requirements change, decisions, structure)
+- Universal workflow selection
+- Universal conventions and do-not rules
+
+### Step 2: For each selected extension, merge additively
+
+For each extension file, extract and inject:
+
+| Section | Merge action | Injection point |
+|---------|-------------|-----------------|
+| Scoping rules | Append rows to scoping table | Before the phase completion row |
+| Cascade rules | Append rows to cascade table | After the "New domain area" row |
+| Workflow | Append line to workflow section | After the "First session" line |
+| Conventions | Append items to conventions list | After the "Propose plans" convention |
+| Do-not rules | Append items to do-not list | After the "Load multiple specialist" rule |
+
+### Step 3: Update PROJECT-PROFILE.md
+
+Record which extensions were applied and their source (setup.sh or manual).
+
+### Step 4: Remove instruction comments
+
+Strip all `<!-- INSTRUCTION: ... -->` comments from the merged entry point.
+
+## Scoping rule composition
+
+When multiple extensions are active, the scoping table grows to include all extension rows. The agent classifies queries against ALL rows and routes to the best match.
+
+**Priority rules for overlapping patterns:**
+1. Project-specific scoping table rows take precedence over registry patterns
+2. More specific query types take precedence over general ones
+3. If ambiguous between extensions, ask the user (STT-02 flagUncertainty)
+
+**Example: code + data project scoping table:**
+
+```markdown
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Planning / roadmap** | REQUIREMENTS.md, ROADMAP.md | STATE.md, PLAN.md |
+| **Context refresh** | .context/ (all), project structure | .context/, this file |
+| **Code change** | .context/BASE.md + relevant specialist, test files | Source files, test files, .context/BASE.md |
+| **Bug fix** | .context/BASE.md + relevant specialist, test files | Source files, test files |
+| **Data ingest** | .context/BASE.md | .context/BASE.md, specialist stubs |
+| **Schema query** | .context/BASE.md + .context/SCHEMA.md | -- |
+| **Phase completion** | SUMMARY.md | SUMMARY.md, STATE.md, ROADMAP.md |
+| **Backlog / ideas** | todos/backlog.md | todos/backlog.md |
+```
+
+## Cascade rule composition
+
+Cascade rules from multiple extensions coexist. All cascade rules are checked after every file change — there is no conflict between extensions because cascade rules trigger on different file types.
+
+**If two cascade rules match the same trigger**: Both propagation sets apply (union of dependent files).
+
+## Manual composition (without setup.sh)
+
+To add an extension to an existing project:
+
+1. Read the extension file (e.g., `code-project.md`)
+2. Copy scoping rules into your entry point's scoping table
+3. Copy cascade rules into your entry point's cascade table
+4. Copy the workflow line into your workflow section
+5. Copy conventions and do-not items into your lists
+6. Update `PROJECT-PROFILE.md` extension stack table
+7. Delete instruction comments if present
+
+To remove an extension: reverse the process — delete the rows that came from that extension file.
+
+## Adding extensions mid-project
+
+Extensions can be added at any time without re-running setup.sh:
+
+1. Follow the manual composition steps above
+2. Run a context refresh (WF-03) to update .context/ files for the new domain
+3. Update PROJECT-PROFILE.md with the new extension and current date
+4. Record the change in STATE.md as a decision
+
+The lifecycle stage does not need to change when adding an extension. A project in Evolution that adds data exploration continues in Evolution — it just has more query types available.

package/templates/extensions/analytical-system.md

@@ -0,0 +1,96 @@
+# Analytical System Extension
+
+<!-- INSTRUCTIONS FOR USE:
+     This extension adds analytical/prompt-system-specific scoping rules, cascade rules,
+     workflow, and conventions to your entry point. To apply:
+
+     1. Open your entry point (AGENT.md, CLAUDE.md, or .cursorrules)
+     2. Add the scoping rules below to your existing scoping rules table
+     3. Add the cascade rules below to your existing cascade table
+     4. Add the workflow line to your workflow section
+     5. Add the conventions and do-not items to your existing lists
+     6. Delete this file after merging — it's a reference, not a runtime file
+
+     Derived from: feature-registry.yaml (v1.4) query_patterns [analytical] + WF-06
+     Specialists referenced: COMPOSITION.md, EVALUATION.md, EXECUTION.md, DOMAIN.md, UI_CONTEXT.md
+     Key difference: analytical systems iterate — compose, evaluate, refine cycles are the norm
+-->
+
+## Additional scoping rules
+
+<!-- Append these rows to your entry point's scoping rules table -->
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Chain work** | .context/BASE.md + .context/EXECUTION.md, pipeline config | Pipeline files, .context/EXECUTION.md, .context/BASE.md (if chain structure changed) |
+| **Evaluation** | .context/BASE.md + .context/EVALUATION.md, scoring rubrics | Evaluation results, .context/EVALUATION.md |
+| **Composition** | .context/BASE.md + .context/COMPOSITION.md, existing templates | Prompt templates, .context/COMPOSITION.md |
+| **Domain research** | .context/BASE.md + .context/DOMAIN.md | .context/DOMAIN.md, STATE.md (research findings) |
+
+## Additional cascade rules
+
+<!-- Append these rows to your entry point's cascade table -->
+
+| When this changes | Also update |
+|------------------|-------------|
+| Pipeline stage added/removed | .context/EXECUTION.md (stage inventory), .context/BASE.md (chain map), downstream stage specs |
+| Evaluation criteria changed | .context/EVALUATION.md (scoring rubric), affected pipeline stage specs |
+| Prompt template modified | .context/COMPOSITION.md (template registry), .context/EVALUATION.md (if scoring affected) |
+| New domain knowledge added | .context/DOMAIN.md (knowledge base), .context/COMPOSITION.md (if templates reference domain) |
+| Chain orchestration config changed | .context/EXECUTION.md (execution flow), .context/BASE.md (if architecture changed) |
+
+## Additional workflow
+
+<!-- Add this line to your entry point's workflow section -->
+
+- **Analytical system** — Discover (identify chains) → Map chains (build chain model) → Build context (specialist files) → Compose (build artifacts) → Evaluate (score against criteria) → Refine (iterate)
+
+## Additional conventions
+
+<!-- Append these to your entry point's conventions list -->
+
+- Every prompt template must have evaluation criteria before deployment
+- Chain changes cascade downstream — upstream stage changes require downstream spec review
+- Evaluation results are recorded with version and date for trend tracking
+- Domain knowledge is captured in specialist files, not embedded in prompts
+- Compose-evaluate-refine is iterative — track iteration count in STATE.md
+
+## Additional do-not items
+
+<!-- Append these to your entry point's do-not list -->
+
+- Deploy prompts without evaluation criteria defined
+- Embed domain knowledge directly in prompt templates — use .context/DOMAIN.md references
+
+## Recommended specialists
+
+<!-- Create these .context/ files as your analytical system grows -->
+
+| Specialist | Create when | Key sections |
+|---|---|---|
+| .context/COMPOSITION.md | Prompt templates or chain composition exists | Template registry, composition patterns, variable schemas, version history |
+| .context/EVALUATION.md | Evaluation criteria or scoring rubrics exist | Scoring rubrics, evaluation methodology, baseline results, trend data |
+| .context/EXECUTION.md | Pipeline stages or orchestration config exists | Stage inventory, execution flow, input/output contracts, stage dependencies |
+| .context/DOMAIN.md | Domain-specific knowledge drives prompt design | Knowledge base, terminology, constraints, reference materials |
+| .context/UI_CONTEXT.md | User-facing interface exists for the analytical system | UI components, interaction patterns, display conventions, user workflows |
+
+## BASE.md analytical map template
+
+<!-- Use this structure for the analytical map section of BASE.md -->
+
+```markdown
+## Chain architecture
+| Chain | Stages | Input | Output | Evaluation |
+|---|---|---|---|---|
+| {chain_name} | {stage count} | {input type} | {output type} | {evaluation method} |
+
+## Pipeline stages
+| Stage | Chain | Purpose | Input | Output | Dependencies |
+|---|---|---|---|---|---|
+| {stage_name} | {chain} | {what it does} | {input format} | {output format} | {upstream stages} |
+
+## Evaluation criteria
+| Criterion | Target | Current | Method |
+|---|---|---|---|
+| {criterion_name} | {target score/metric} | {latest result} | {how evaluated} |
+```

package/templates/extensions/code-project.md

@@ -0,0 +1,77 @@
+# Code Project Extension
+
+<!-- INSTRUCTIONS FOR USE:
+     This extension adds code-specific scoping rules, cascade rules, conventions,
+     and workflow to your entry point. To apply:
+
+     1. Open your entry point (AGENT.md, CLAUDE.md, or .cursorrules)
+     2. Add the scoping rules below to your existing scoping rules table
+     3. Add the cascade rules below to your existing cascade table
+     4. Add the workflow line to your workflow section
+     5. Add the conventions and do-not items to your existing lists
+     6. Delete this file after merging — it's a reference, not a runtime file
+
+     Derived from: feature-registry.yaml (v1.1) query_patterns [code] + WF-02
+     Specialists referenced: customize the specialist names to match your project
+-->
+
+## Additional scoping rules
+
+<!-- Append these rows to your entry point's scoping rules table -->
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Code change** | .context/BASE.md + relevant specialist, test files for affected modules | Source files, test files, .context/BASE.md (if structure changed) |
+| **Bug fix** | .context/BASE.md + relevant specialist, test files for affected area | Source files, test files |
+| **Dependency update** | .context/BASE.md, package files | Package manifest, lock file, .context/BASE.md (deps table) |
+| **Database work** | .context/BASE.md + .context/DATABASE.md | Schema files, migrations, models, .context/DATABASE.md |
+| **API work** | .context/BASE.md + .context/API.md | Route files, tests, .context/API.md |
+| **Deployment / infra** | .context/BASE.md + .context/INFRASTRUCTURE.md | Config files, pipeline definitions |
+
+## Additional cascade rules
+
+<!-- Append these rows to your entry point's cascade table -->
+
+| When this changes | Also update |
+|------------------|-------------|
+| Database schema | Run migration generation, update type imports, run integration tests, update .context/DATABASE.md |
+| API route contract | Update client calls, update API tests, update .context/API.md |
+| New module/directory | Update .context/BASE.md codebase map, consider new .context/ specialist |
+| Package added/removed | Update .context/BASE.md dependencies, verify compatibility |
+| Environment variable added | Update .env.example, update deployment configs, update .context/BASE.md |
+
+## Additional workflow
+
+<!-- Add this line to your entry point's workflow section -->
+
+- **Code change** — Review (read tests first) → Plan (include cascade impacts) → Implement (test-adjacent) → Context-sync (update .context/) → Update
+
+## Additional conventions
+
+<!-- Append these to your entry point's conventions list -->
+
+- Write/update tests alongside every code change — never defer
+- All user input validated before processing
+- Follow existing code patterns in adjacent files
+- Atomic commits with conventional commit messages
+- Run affected tests before considering a change complete
+
+## Additional do-not items
+
+<!-- Append these to your entry point's do-not list -->
+
+- Defer tests to "later" — they are part of the change
+- Commit .env files or include secrets in code
+
+## Recommended specialists
+
+<!-- Create these .context/ files as your project grows -->
+
+| Specialist | Create when | Key sections |
+|---|---|---|
+| .context/DATABASE.md | Project uses a database | Schema overview, migration conventions, query patterns |
+| .context/API.md | Project has API endpoints | Route inventory, auth conventions, error format |
+| .context/TESTING.md | Complex test infrastructure | Test categories, runner config, coverage targets |
+| .context/SECURITY.md | Auth/authz code exists | Security conventions, OWASP checklist, audit triggers |
+| .context/INFRASTRUCTURE.md | CI/CD pipeline exists | Pipeline stages, build requirements, deploy process |
+| .context/INTEGRATIONS.md | External service integrations | Service inventory, auth methods, contract boundaries |

package/templates/extensions/data-exploration.md

@@ -0,0 +1,117 @@
+# Data Exploration Extension
+
+<!-- INSTRUCTIONS FOR USE:
+     This extension adds data-exploration-specific scoping rules, cascade rules,
+     workflow, and exploration commands to your entry point. To apply:
+
+     1. Open your entry point (AGENT.md, CLAUDE.md, or .cursorrules)
+     2. Add the scoping rules below to your existing scoping rules table
+     3. Add the cascade rules below to your existing cascade table
+     4. Add the workflow line to your workflow section
+     5. Add the conventions and do-not items to your existing lists
+     6. Delete this file after merging — it's a reference, not a runtime file
+
+     Derived from: feature-registry.yaml (v1.1) query_patterns [data] + WF-05
+     Specialists referenced: SCHEMA.md, DOCUMENTS.md, RELATIONSHIPS.md
+     Key difference: most exploration queries are READ-ONLY — no file changes, no cascades
+-->
+
+## Additional scoping rules
+
+<!-- Append these rows to your entry point's scoping rules table.
+     Note: most data queries are read-only (write column is "--") -->
+
+| Query type | Read before acting | Update after acting |
+|------------|-------------------|-------------------|
+| **Data ingest** | .context/BASE.md | .context/BASE.md (data inventory), specialist stubs |
+| **Schema query** | .context/BASE.md + .context/SCHEMA.md | -- |
+| **Document search** | .context/BASE.md + .context/DOCUMENTS.md | -- |
+| **Entity exploration** | .context/BASE.md + specialist containing entity | STATE.md (exploration path) |
+| **Relationship query** | .context/BASE.md + .context/RELATIONSHIPS.md | -- |
+| **Analytical query** | .context/BASE.md + .context/SCHEMA.md | -- |
+| **Quality check** | .context/BASE.md + .context/SCHEMA.md | -- |
+| **Add dimension** | .context/BASE.md | .context/BASE.md (queryable dimensions) |
+| **Add reference** | .context/BASE.md + relevant specialist | Specialist file |
+
+## Additional cascade rules
+
+<!-- Append these rows to your entry point's cascade table -->
+
+| When this changes | Also update |
+|------------------|-------------|
+| New data source added | .context/BASE.md (data inventory), relevant specialist (schema or document index) |
+| Schema change detected | .context/SCHEMA.md (field inventory), .context/BASE.md (if new dimension), .context/RELATIONSHIPS.md (if join paths affected) |
+| New entity discovered | Relevant specialist (entity registry), .context/BASE.md (if new queryable dimension) |
+| New document added | .context/DOCUMENTS.md (index and topics), .context/BASE.md (if new data source) |
+| Derived metric added | .context/SCHEMA.md (metrics section), .context/BASE.md (queryable dimensions) |
+| User corrects a reference | Relevant specialist (update entry), cascade to cross-references |
+
+## Additional workflow
+
+<!-- Add this line to your entry point's workflow section -->
+
+- **Data exploration** — Ingest (scan sources) → Map (build data model) → Reference (build navigable artifacts) → Explore (interactive querying) → Refine (evolve understanding)
+
+## Exploration commands
+
+<!-- These named patterns help users discover available interactions.
+     The agent recognizes these and routes to the appropriate specialist. -->
+
+| Command pattern | What the agent does | Specialist loaded |
+|---|---|---|
+| `explore {entity}` | Show all references and related data for an entity | Specialist containing entity |
+| `schema {table}` | Show full field inventory for the table | SCHEMA.md |
+| `search {topic}` | Find all documents and data covering this topic | DOCUMENTS.md |
+| `relate {A} to {B}` | Show connection paths between two entities/tables/documents | RELATIONSHIPS.md |
+| `quality {source}` | Show data quality report for the source | SCHEMA.md |
+| `timeline {topic}` | Show chronological progression across sources | DOCUMENTS.md |
+| `dimensions` | List all queryable dimensions | BASE.md |
+| `gaps` | Show known gaps in data coverage | BASE.md + relevant specialist |
+| `summary {scope}` | Generate executive summary for a scope | BASE.md + relevant specialist |
+
+## Additional conventions
+
+<!-- Append these to your entry point's conventions list -->
+
+- Context files contain understanding, not raw data — use the abstraction ladder
+- Most exploration queries are read-only — don't create unnecessary file changes
+- Progressively reveal available exploration commands as the user explores
+- Every reference entry must be addressable, cross-linked, and source-attributed
+
+## Additional do-not items
+
+<!-- Append these to your entry point's do-not list -->
+
+- Load raw data into context files — context contains understanding, not data
+- Attempt to hold entire datasets in context — use schema + references instead
+
+## Recommended specialists
+
+<!-- Create these .context/ files during the Ingest and Map stages -->
+
+| Specialist | Create when | Key sections |
+|---|---|---|
+| .context/SCHEMA.md | Structured data exists (CSV, database, spreadsheets) | Field inventory, derived metrics, data quality notes |
+| .context/DOCUMENTS.md | Document collection exists (PDFs, markdown, wiki) | Document index, topic taxonomy, entity registry, cross-references |
+| .context/RELATIONSHIPS.md | Multiple data sources that connect | Join paths, cross-source links, navigation patterns |
+
+## BASE.md data map template
+
+<!-- Use this structure for the data map section of BASE.md -->
+
+```markdown
+## Data inventory
+| Source | Type | Records | Key columns | Location |
+|---|---|---|---|---|
+| {source_name} | {structured/documents/mixed} | {count} | {key fields} | {file path} |
+
+## Schema overview
+| Table | Primary key | Core dimensions | Joins to |
+|---|---|---|---|
+| {table} | {key} | {dimensions} | {related tables} |
+
+## Queryable dimensions
+| Dimension | What the user can ask | Data source |
+|---|---|---|
+| {dimension_name} | {sample questions} | {tables/documents} |
+```

package/templates/full/.context/BASE.md

@@ -0,0 +1,68 @@
+# Base Context — Always Loaded
+
+<!-- INSTRUCTION: This file is loaded EVERY session alongside the entry point.
+     Keep it under 100 lines. It gives the agent persistent understanding of
+     your project's architecture and structure. -->
+
+## What this system is
+
+<!-- INSTRUCTION: 2-3 sentences describing your project's architecture.
+     What does it do? What are the main components? What technologies? -->
+
+{Describe your project architecture here}
+
+## System model
+
+<!-- INSTRUCTION: How do the project's components relate to each other?
+     A simple flow or diagram description. For code projects, describe
+     the data/control flow. -->
+
+{component A} --> {component B} --> {component C}
+
+## Codebase map
+
+<!-- INSTRUCTION: Table of directories, their purposes, and key patterns.
+     The agent uses this to navigate without re-exploring every session.
+     For existing codebases, ask the agent: "Scan the codebase and populate this map" -->
+
+| Path | Purpose | Key patterns |
+|------|---------|-------------|
+| {src/} | {Source code} | {language, framework} |
+| {tests/} | {Test suite} | {testing framework} |
+
+## Dependencies
+
+<!-- INSTRUCTION: Key external dependencies and their roles.
+     Not an exhaustive list — just the ones that affect architecture decisions. -->
+
+| Dependency | Role |
+|------------|------|
+| {framework} | {What it provides} |
+
+## Pairing protocol
+
+<!-- INSTRUCTION: Maps task types to specialist context files.
+     Add rows as you create specialist .context/ files.
+     Each query type should pair BASE.md with exactly ONE specialist. -->
+
+| Task type | Pair BASE.md with |
+|-----------|-------------------|
+| {domain-work-type} | .context/{SPECIALIST}.md |
+
+<!-- INSTRUCTION: To create a specialist file, identify a recurring domain area
+     in your project that needs its own deep context. Keep each specialist
+     under 150 lines. The agent can help create them during context refresh. -->
+
+## Navigation
+
+<!-- INSTRUCTION: Quick reference to key project files and their roles. -->
+
+| File | Purpose |
+|------|---------|
+| {AGENT.md / CLAUDE.md} | Agent entry point — scoping, cascade |
+| STATE.md | Current position and decisions |
+| PLAN.md | Current atomic task |
+| ROADMAP.md | Phase breakdown and progress |
+| PROJECT.md | Project vision and structure |
+| REQUIREMENTS.md | What must be achieved, with phase traceability |
+| SUMMARY.md | Execution history — session audit trail |

package/templates/full/.context/COMPOSITION.md

@@ -0,0 +1,47 @@
+# Composition Context
+
+Pair with: `.context/BASE.md`
+Use when: query type is **composition** (building, combining, or refining composed outputs)
+
+## Template registry
+
+<!-- List your composable templates/fragments/prompts here.
+     Each entry: name, purpose, inputs, output format, version. -->
+
+| Template | Purpose | Inputs | Output | Version |
+|----------|---------|--------|--------|---------|
+| {template-name} | {what it produces} | {what it needs} | {format} | {version} |
+
+## Composition patterns
+
+<!-- Document how templates combine into larger outputs.
+     Each pattern: which templates, in what order, with what parameters. -->
+
+| Pattern | Templates used | Assembly order | Parameters |
+|---------|---------------|----------------|------------|
+| {pattern-name} | {template list} | {sequence} | {key params} |
+
+## Variable schemas
+
+<!-- Define the variables/parameters that flow between templates.
+     Each variable: name, type, source, used by. -->
+
+| Variable | Type | Source | Used by |
+|----------|------|--------|---------|
+| {variable-name} | {type} | {where it comes from} | {which templates} |
+
+## Composition rules
+
+<!-- Constraints and validation rules for composition.
+     What combinations are valid, what's prohibited, ordering requirements. -->
+
+- {rule description}
+
+## Version history
+
+<!-- Track changes to the composition system.
+     What changed, why, impact on existing compositions. -->
+
+| Date | Change | Impact |
+|------|--------|--------|
+| {date} | {what changed} | {what it affects} |