Think & Plan

The Think & Plan domain provides an agentic specification methodology that turns a prioritized backlog issue into persistent, machine-consumable records: think.md (the Think record) and plan.md (the Plan record). It implements stages 2 — Think and 3 — Plan of the Agentic Software Factory and follows the Triage stage.

Rather than narrative PRDs, Coding Pal enforces two stages: Think chooses and records an approach, constraints, and blast radius; Plan defines file scope, criteria, atomic steps, and tests. AI decides and approves autonomously at every risk tier, including API, schema, High, and Critical changes. Required controls, rollback evidence, and retry limits remain enforced. People intervene on unresolved failures or requested checkpoints.

Domain Architecture

Capabilities Matrix

Capability	Invocation / Entry Point	Specialist Agent	Scoping Instruction	Supporting Skill	Output Artifact
Business Needs to Specifications	`/think` & `/plan` or `Thinker` & `Planner` agents (CI)	`Thinker` & `Planner`	`think` & `plan`	`think` & `plan`	`specs/issue-<n>/think.md` and `plan.md` (options, blast radius, acceptance criteria, atomic steps)

The Two Records

	`think.md` (Think record)	`plan.md` (Plan record)
Owner	Developer + Architect	Architect + Developer
Decides	The approach	The sequence
Contains	Options considered, chosen approach, system flow, constraints and invariants, blast radius, decision record, Persistent Context updates, open questions	File scope and boundaries, prerequisites, acceptance criteria, implementation checklist, test plan, open questions and assumptions, blast radius check
Code	None	None (code is written once in Code)
Reads	The backlog issue and `triage.md`, Persistent Context, the codebase	The validated `think.md`
Approved by	Explicit automation identity and date in `## Chosen Approach`	Explicit automation identity and date in `## Approval`

The Plan reads Think's constraints and tier. After validation, both records use Approved By: Automated by <identity> on YYYY-MM-DD, with Plan dated no earlier than Think. Human approval remains supported for requested checkpoints; automation must never forge a human signature.

Capability Workflows

1. Business Needs to Specifications: Think & Plan

When to Run: For every backlog issue the Product Owner decides as todo. Interactively in the IDE (planning session) or headlessly in CI when the decision:todo label is applied (or on issues: [opened] where Triage is not used).
Why It Replaces Traditional Specs:
- Traditional PRDs and narrative design docs are verbose, full of unstated assumptions, and swamp the LLM context window with conversational prose.
- In an agentic operating model, specifications are actionable data structures for models:
  1. think.md records the options weighed, the approach chosen, and the blast radius, so the decision is reviewable before anything is planned.
  2. plan.md sequences the implementation into atomic, dependency-ordered steps. Each step carries its files, action, a narrow verification, and a bootable check, and traces to the acceptance criteria it serves.
- Downstream build agents consume plan.md in dependency order in a clean context session, verifying each step before proceeding.
Workflow Steps:
1. Phase 1: Think:
  - Interactive (IDE): Run /think 42 (or /think specs/issue-42) to invoke the Thinker agent and save the Think record to specs/issue-42/think.md.
  - Headless (GitHub Action): Triggered by the Product Owner's decision:todo label, invoking the Thinker agent (think.agent.md). Where Triage is not used, trigger on issues: [opened] with the issue title and body.
  - The agent validates triage.md at the final stage and proceeds only on todo, reusing the Triage evidence and system mapping.
  - It scans the codebase and Persistent Context, weighs 2 to 4 options, selects one, and classifies blast radius. Required decisions are accepted with an Automation decider and Automated by <identity> on YYYY-MM-DD attribution after validation.
2. Phase 2: Plan:
  - Interactive (IDE): In a clean session, run /plan 42 (or /plan specs/issue-42) to invoke the Planner agent and generate specs/issue-42/plan.md from specs/issue-42/think.md.
  - Headless (CI): The Planner agent (plan.agent.md) synthesizes plan.md from the validated think.md.
  - Emits the file scope, acceptance criteria, steps with Files, Action, Verification, Bootable Check, and Serves, the test plan, and the blast radius check.
3. Phase 3: Automated Validation:
  bash
```
node .agents/skills/think/scripts/validate-think.mjs --think specs/issue-42/think.md
node .agents/skills/plan/scripts/validate-plan.mjs --dir specs/issue-42
```
  This checks the drafts (--stage draft, the default). After the named approvals are recorded, --stage approved checks them.
4. Phase 4: Agentic Coding:
  - After validation, record automated approval in ## Approval and launch the Code Agent with clean context (/code 42). Human review is an optional requested checkpoint.
  - It implements the steps in dependency order, executing each step's Action, adjusting only as needed to fit the real repository, and keeps the application bootable.

What the Validator Enforces

Check	Why
Exact section order and headings in both records	Predictable structure for reviewers and agents
2 to 4 sequential options, each with trade-offs, cost, and risk	Think records a decision, not a conclusion
Blast radius tier set; rollback named for High and Critical (also when Plan raises the tier)	The tier drives automated validation and rollback evidence in Prove
No source code in `think.md` or `plan.md`, and no checklist or step headings in `think.md`	Code is written once in Code, never in Think or Plan
Critical requires a decision record; autonomous records use an Automation decider and valid automation attribution	Human signatures remain reserved for actual humans
`Approved By` accepts `Automated by <identity> on YYYY-MM-DD` at draft and approved stages; actual human approvals remain supported	Automated Plan approval must not precede Think approval; Pending is incomplete, not approval
Prerequisites & Context holds the `think.md` reference plus at least one more line (dependencies, environment variables, services, or `- None.`)	A bare reference leaves Step 1's setup unstated
3 to 8 sequential `Given ..., then ...` acceptance criteria	Observable, testable statements
Step fields in order (`Files`, `Action`, `Verification`, `Bootable Check`, `Serves`), with `Verification` and `Bootable Check` as commands in backticks	Every step is scoped, checked by a command, and traceable to criteria
Every in-scope file covered by a step; no step outside scope	File scope is the boundary
Every criterion served by a step and present in the test plan, with a serving step	Criteria are provable
Irreversible changes have a reverse step; migration-looking paths cannot claim none	A revert must be able to undo the change
Questions answered before Code (`--allow-open-questions` for drafts)	No open questions reach Code
Blast radius check matches Think, raised tiers are higher and explained	The tier holds for the file scope
Cross-check: every Think Persistent Context update has a plan step	Context changes are planned like any other work
Code fences are opaque	Fenced text cannot break headings or fields

Downstream Execution Discipline

When an AI build agent implements functionality from plan.md:

It reads plan.md in a clean session.
It executes the checklist steps in dependency order, implementing each step's Action inside its declared Files.
For each step, it runs the step's Verification command and asserts that the application still boots (Bootable Check).
Only when every step's checks and the deterministic controls pass does it open the pull request with its record.

The plan's In Scope list feeds scope-guard.mjs in the prove skill, and the AC-n identifiers give Prove a stable handle for criteria-test verification (verify-criteria.mjs).

Storage & GitHub Issue Attachment Pattern

When automating specifications from GitHub issues in CI/CD, specifications follow the Issue Comment + Dedicated Branch pattern:

Non-destructive Issue Comment: The action never overwrites the issue description. Leaving the human words intact preserves the authentic requirement while keeping discussions and reviews threaded.
Collapsible Visual Layout: Full specifications are posted in a comment formatted with HTML <details> tags:
- think.md enclosed in <details><summary>🧠 <b>think.md (Options, Blast Radius & Constraints)</b></summary> ... </details>.
- plan.md enclosed in <details open><summary>📝 <b>plan.md (Scope, Criteria & Steps)</b></summary> ... </details>.
Dedicated Branch Storage: Files are committed to specs/issue-<number>/ on branch specs/issue-<number>, next to triage.md.

Falsifiable Done When:
- think.md passes skills/think/scripts/validate-think.mjs and plan.md passes skills/plan/scripts/validate-plan.mjs with exit code 0, including the cross-check.
- Required decisions pass validation and record explicit automation attribution without fabricated human signatures.
- Both Approved By fields record the automation identity and date; --stage approved passes before automatic continuation.
- Zero production or test files were modified during specification generation.

Think & Plan ​

Domain Architecture ​

Capabilities Matrix ​

The Two Records ​

Capability Workflows ​

1. Business Needs to Specifications: Think & Plan ​

What the Validator Enforces ​

Downstream Execution Discipline ​

Storage & GitHub Issue Attachment Pattern ​

Related Catalogs & Schemas ​