agent-method 1.5.0

package/templates/starter/CLAUDE.md

@@ -0,0 +1,113 @@
+# {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. Check `PROJECT-PROFILE.md` for lifecycle stage and active extensions
+4. 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) |
+| **Project discovery** | Project structure, package files, key source files | .context/BASE.md, .context/ specialists, STATE.md |
+| **{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) |
+| Lifecycle stage change | PROJECT-PROFILE.md (update stage + date), STATE.md (record decision) |
+| 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
+- **Discovery (brownfield)** — Inventory, Map-dependencies, Extract-patterns, Assess, Bootstrap
+
+## 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/starter/PLAN.md

@@ -0,0 +1,67 @@
+# Current Plan
+
+<!-- INSTRUCTION: This file contains ONE task at a time. Replace the entire
+     contents when starting a new task — never accumulate multiple plans.
+     The agent proposes the plan and waits for human approval before executing. -->
+
+## {Task name}
+
+### Objective
+
+{What this task achieves. One clear sentence.}
+
+### Prerequisites
+
+<!-- INSTRUCTION: What must be true before starting this task? -->
+
+- {Prior phase or task complete}
+- {Required files or context available}
+
+### Dependencies
+
+<!-- INSTRUCTION: What depends on this task? What does this task block? -->
+
+- {Phase/task that depends on this completing}
+
+---
+
+### Step 1: {Step name}
+
+**Objective**: {What this step achieves}
+
+**Read**: {Files to read before this step}
+**Produce**: {Files created or modified by this step}
+
+**Substeps**:
+- a. {First substep}
+- b. {Second substep}
+
+**Verify**: {How to confirm this step is complete and correct}
+
+---
+
+### Step 2: {Step name}
+
+**Objective**: {What this step achieves}
+
+**Read**: {Files to read}
+**Produce**: {Files created or modified}
+
+**Verify**: {Verification criteria}
+
+---
+
+<!-- INSTRUCTION: Add more steps as needed. Each step should have:
+     - Clear objective
+     - Read/produce specs (what files are involved)
+     - Substeps (if complex)
+     - Verification criteria (how to confirm it's done right) -->
+
+### Completion criteria
+
+{Task name} is done when:
+1. {Criterion 1 — specific and measurable}
+2. {Criterion 2}
+3. {Criterion 3}
+
+**Next after {task name}**: {What comes next}

package/templates/starter/PROJECT-PROFILE.md

@@ -0,0 +1,44 @@
+# Project Profile
+
+<!-- INSTRUCTION: This file is maintained by the agent. It tracks your project's
+     type, lifecycle stage, and active extensions. The agent reads this to adjust
+     feature priorities and workflow selection. You can also update it manually
+     when your project's situation changes.
+
+     Fill in the initial values during setup. The agent updates lifecycle stage
+     and maturity as the project evolves. -->
+
+## Project identity
+
+- **Types**: [{project-type}]
+- **Extensions**: [{extensions-applied}]
+
+<!-- INSTRUCTION: Project types: code, data, analytical, mixed, general.
+     Extensions: code-project, data-exploration, analytical-system, or none. -->
+
+## Lifecycle
+
+- **Stage**: {stage}
+- **Maturity**: {maturity}
+- **Last transition**: {date} ({from} -> {to})
+
+<!-- INSTRUCTION: Lifecycle stages:
+     - discovery: Understanding an existing project (brownfield entry)
+     - design: Defining architecture and structure (greenfield start)
+     - development: Building and iterating (active implementation)
+     - evolution: Maintaining and extending (stable baseline)
+
+     Maturity levels: new, early, established, legacy.
+     The agent suggests transitions; you decide when to move. -->
+
+## Extension stack
+
+| Extension | Applied | Source |
+|-----------|---------|--------|
+| code-project | {yes/no} | {setup.sh / manual} |
+| data-exploration | {yes/no} | {setup.sh / manual} |
+| analytical-system | {yes/no} | {setup.sh / manual} |
+
+<!-- INSTRUCTION: Track which extensions are active. Extensions can be added
+     mid-project without re-running setup.sh — merge the extension file
+     into your entry point manually and update this table. -->

package/templates/starter/PROJECT.md

@@ -0,0 +1,46 @@
+# {Your Project Name}
+
+<!-- INSTRUCTION: Replace with a 2-3 sentence description of your project.
+     Include what it does, who it's for, and what technologies it uses. -->
+{Describe what your project does and who it's for}
+
+## Problem
+
+<!-- INSTRUCTION: What problem does this solve? 2-3 bullet points. -->
+
+- {Problem statement 1}
+- {Problem statement 2}
+
+## Solution
+
+<!-- INSTRUCTION: How does the project solve the problem? Brief description of the approach. -->
+
+{Describe your approach}
+
+## Project structure
+
+<!-- INSTRUCTION: Table of top-level directories and their purposes.
+     The agent uses this to understand the project layout.
+     For existing codebases, ask the agent to help populate this from a scan. -->
+
+| Path | Purpose |
+|------|---------|
+| {src/} | {Source code} |
+| {docs/} | {Documentation} |
+
+## Audiences
+
+<!-- INSTRUCTION: Who interacts with this project? Users, developers, managers, agents? -->
+
+| Audience | What they need |
+|----------|---------------|
+| {Developer} | {Working code, clear architecture} |
+| {User} | {Functional product} |
+
+## Principles
+
+<!-- INSTRUCTION: 3-5 guiding principles for decision-making on this project. -->
+
+1. {Principle 1}
+2. {Principle 2}
+3. {Principle 3}

package/templates/starter/ROADMAP.md

@@ -0,0 +1,39 @@
+# Roadmap
+
+<!-- INSTRUCTION: Define phases with deliverables and gate criteria.
+     Each phase should have:
+     - A clear objective (1 sentence)
+     - A deliverable table (what, requirement, status)
+     - A gate (how you know the phase is done)
+     Copy the Phase template below for each phase in your project. -->
+
+## Phase 1 — {Phase name} [status]
+
+<!-- INSTRUCTION: Replace {Phase name} with a descriptive name.
+     Set [status] to one of: current, pending, done -->
+
+{One sentence describing what this phase achieves.}
+
+| Deliverable | Requirement | Status |
+|-------------|-------------|--------|
+| {Deliverable 1} | {Which requirement it satisfies} | pending |
+| {Deliverable 2} | {Which requirement it satisfies} | pending |
+
+**Gate**: {How you know this phase is complete. Be specific — measurable criteria.}
+
+---
+
+## Phase 2 — {Phase name} [pending]
+
+{One sentence describing what this phase achieves.}
+
+| Deliverable | Requirement | Status |
+|-------------|-------------|--------|
+| {Deliverable 1} | {Requirement} | pending |
+
+**Gate**: {Completion criteria}
+
+---
+
+<!-- INSTRUCTION: Add more phases as needed. Each phase should be achievable
+     in 1-5 sessions. If a phase takes longer, split it. -->

package/templates/starter/SESSION-LOG.md

@@ -0,0 +1,41 @@
+# Session Log
+
+Append-only session observation log for case study data collection. Each session adds a micro-entry at close. This file is read-only during extraction (never during normal work).
+
+<!-- AGENT INSTRUCTION: At the end of every session, append a new entry below using this format.
+     Do NOT read this file during normal work — only append to it.
+     Do NOT modify or delete previous entries.
+     When this file exceeds 300 lines, archive older entries to session-log/batch-{N}.md -->
+
+## Project context
+
+| Field | Value |
+|-------|-------|
+| Project name | {project name} |
+| Project type | {code / data / analytical / mixed / general} |
+| Integration profile | {lite / standard / full} |
+| Extension(s) | {code-project / data-exploration / analytical-system / none} |
+| Observation started | {date} |
+
+## Observation checklist
+
+At session close, reflect on these before writing the micro-entry:
+1. Which workflow did this session follow?
+2. Which query types were encountered?
+3. Which features visibly activated? (context loading, cascade, decision recording, scoping)
+4. Were any cascades expected but missed?
+5. Were any decisions deferred instead of recorded immediately?
+6. Was there friction with any methodology rule?
+7. Any degradation signals? (HAI-05: cascade misses, instruction loss, shallow context)
+
+## Session entries
+
+<!-- Append new entries below. Format:
+### S{N} — {YYYY-MM-DD} — {brief title}
+Model: {model} | Profile: {profile} | Workflow: {WF-XX}
+Queries: {query types encountered}
+Features: {feature IDs activated}
+Cascades: {triggered}/{expected} | Decisions: {count}
+Friction: {none | brief description}
+Finding: {none | observation with methodology implication}
+-->

package/templates/starter/STATE.md

@@ -0,0 +1,42 @@
+# State
+
+## Current position
+
+- **Phase**: {Phase name or number}
+- **Status**: {What's happening now}
+- **Next**: {What comes after the current work}
+- **Active context**: `.context/BASE.md`
+
+<!-- INSTRUCTION: Update this section every session. The next session reads this
+     to know where to pick up. Be specific about what's in progress and what's next. -->
+
+## Decisions
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+<!-- INSTRUCTION: Add decisions HERE, in the SAME response as the work that
+     produced them. Never defer to end of session. If the session is interrupted,
+     the decision survives. Format: date, what was decided, why. -->
+
+## Blockers
+
+<!-- INSTRUCTION: List anything preventing progress. Remove when resolved. -->
+
+None currently.
+
+## Open questions
+
+<!-- INSTRUCTION: When the agent encounters uncertainty, it writes a numbered
+     question here. When resolved, don't delete — add the resolution inline.
+     This preserves reasoning history. -->
+
+1. {Open question — describe what's uncertain and why it matters}
+
+## Variant log
+
+<!-- INSTRUCTION: Optional. Track experiment variants if your project involves
+     A/B testing, prompt variants, or configuration comparison. Delete if unused. -->
+
+| Run | Scenario | Variant | Avg Score | Notes |
+|-----|----------|---------|-----------|-------|
+| -- | -- | -- | -- | No runs executed yet |