Skip to main content

Specification Engineering

Specification engineering is writing structured documents that both humans and AI agents can execute. In Green Goods, specs drive agent workflows through clearly defined phases, acceptance criteria, and verification steps.

Specification Types​

Subagent Dispatches (the Agent tool)​

The repo no longer commits agent specification files -- the last two (cracked-coder and oracle) were retired with the lean-skills consolidation. Specialization now travels in the dispatch itself: a task-scoped prompt to one of Claude Code's built-in subagent types (Explore for read-only search, general-purpose for multi-step work, Plan for implementation strategy).

Agent tool dispatch:
  subagent_type: general-purpose
  description: Migrate vault history hooks
  prompt: |
    Work only in packages/shared/src/hooks/vault/**.
    Task: <bounded task with acceptance criteria>.
    Validation: bun run test -- <targeted file>; report evidence.
    This repo runs concurrent agents -- stay in the listed paths and
    surface unexpected state in your report instead of fixing it.

A good dispatch prompt reads like a mini-spec: bounded paths, explicit acceptance criteria, named validation commands, and the report shape expected back. Durable knowledge (patterns, invariants, conventions) stays in CLAUDE.md, AGENTS.md, and .claude/context/*.md -- the dispatch only carries what is unique to the task.

Feature Specifications (.plans/active/<feature-slug>/spec.md)​

Detailed requirements for complex features live inside the feature hub described under Plan Files. Structure:

  1. Problem statement -- What problem does this solve?
  2. User stories -- Who benefits and how?
  3. Technical design -- Architecture, data flow, dependencies
  4. Research evidence -- Source, tests, docs, and existing patterns reviewed before planning
  5. Human judgment points -- Decisions, protected surfaces, and tradeoffs that should stay visible
  6. Acceptance criteria -- Testable conditions for completion
  7. Edge cases -- Known failure modes and how to handle them

Plan Files (.plans/)​

Plan files are the durable feature hub for complex work, not just an intermediate PLAN-phase artifact. A user asking for "just a plan" may stop after writing the hub without executing, but the same .plans/ entry remains the repo truth during implementation, handoffs, and verification.

.plans/active/<feature-slug>/
  brief.md       # Problem framing and key decisions
  spec.md        # Structured requirements, research evidence, judgment points, acceptance criteria
  plan.todo.md   # Research/plan gate plus ordered implementation checklist
  status.json    # Machine-readable lane and progress state
  eval.md        # Optional verification or acceptance notes
  handoffs/      # Optional human or agent handoff context

Update the active feature hub as work moves forward, especially plan.todo.md and status.json. This keeps resumed sessions and parallel agents aligned on the same source of truth.

Writing Effective Specs​

Testable Acceptance Criteria​

Every criterion should be verifiable without human judgment:

# Good
- [ ] `useGardenActions(undefined, chainId)` returns `{ enabled: false }`
- [ ] Calling `bun run test` passes with 0 failures
- [ ] The barrel export exists in `packages/shared/src/hooks/index.ts`

# Bad
- [ ] The hook works correctly
- [ ] Performance is acceptable
- [ ] Code is clean

Scope Boundaries​

Specs must define what is NOT in scope to prevent agents from over-engineering:

## Out of Scope
- Visual design changes (handled by the `design` skill's direction + implementation docs)
- Contract modifications (requires separate spec + security review)
- i18n for languages other than en/es/pt

Research Evidence​

Before planning implementation, record what the agent or human actually checked:

## Research Evidence
- Existing pattern references: `packages/shared/src/hooks/useExample.ts`
- Source files, tests, or docs reviewed: ...
- Evidence confirmed: ...
- Open inferences or assumptions: ...

This makes it clear when a recommendation is source-backed versus inferred from context.

Human Judgment Points​

Specs should also preserve the decisions that should not be delegated silently:

## Human Judgment Points
- Decisions that need maintainer judgment:
- Protected or high-risk surfaces:
- Tradeoffs to keep visible during review:

These points are not blockers by default. They are review handles so humans keep the right ownership.

Dependency Mapping​

For cross-package work, explicitly list which packages are touched and in what order:

## Packages Affected
1. `packages/shared` -- New hook + tests (build first)
2. `packages/admin` -- New component consuming the hook
3. `packages/client` -- No changes

Skill Specifications (.claude/skills/)​

Skills are specialized instruction sets loaded by agents. Each skill has:

  • Activation criteria -- When to use this skill
  • Patterns -- Code patterns with examples
  • Constraints -- What to avoid
  • Verification -- How to confirm correct application

The project keeps 10 skills -- review, ship, status, plan, debug, clean, audit, qa-triage, doc-feedback, and design -- reserved for procedures and integrations with real orchestration. Domain knowledge that used to live in skills (testing, react, web3, contracts, the PostHog question library, ...) moved to .claude/context/*.md and docs/, so specs reference documentation rather than skill files for patterns.

Spec Review Checklist​

Before handing a spec to an agent:

  1. Are all acceptance criteria mechanically testable?
  2. Is the scope bounded (explicit out-of-scope section)?
  3. Is research evidence recorded with file, test, or doc references?
  4. Are human judgment points explicit?
  5. Are package dependencies listed with build order?
  6. Does the spec reference existing patterns (Cathedral Check)?
  7. Are edge cases listed with expected behavior?
  8. Is the model requirement appropriate for the complexity?

Governance​

Specs are version-controlled alongside the code they describe. The standalone guidance checker and skills registry were retired with the lean-skills consolidation -- the filesystem plus SKILL.md frontmatter is the registry, bun run check:codex-guidance keeps Codex guidance in parity, and the .claude/loop.md maintenance loop greps for stale references to retired surfaces. None of that proves a spec semantically agrees with the code it describes, so specs still need source-backed evidence and explicit acceptance criteria.

Next page

Next best action

Explore the primary AI coding tool used in the Green Goods workflow.

Claude Code