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​

Agent Specifications (.claude/agents/*.md)​

Define agent identity, capabilities, and constraints:

---
name: cracked-coder
description: Implements complex features using strict TDD workflow.
model: opus
tools: [Read, Glob, Grep, Edit, Write, Bash, Task]
skills: [testing, react, contracts]
maxTurns: 50
---

The committed repo surface currently keeps two agent specs and routes most specialization through skills instead of extra checked-in agent files:

AgentPurposeModel
cracked-coderFeature implementation with TDDOpus
oracleArchitecture guidance and analysisOpus

Retired agent roles such as code-reviewer, triage, migration, and storybook-author now live as skill or workflow patterns rather than committed .claude/agents/*.md surfaces.

Feature Specifications (.claude/specs/)​

Detailed requirements for complex features. Structure:

  1. Problem statement -- What problem does this solve?
  2. User stories -- Who benefits and how?
  3. Technical design -- Architecture, data flow, dependencies
  4. Acceptance criteria -- Testable conditions for completion
  5. 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 and acceptance criteria
  plan.todo.md   # 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 `ui` or design workflow, not a separate committed agent spec)
- Contract modifications (requires separate spec + security review)
- i18n for languages other than en/es/pt

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 currently has 19 active top-level skill directories, with additional historical wrappers under _archived/, covering domains from testing to ui to web3.

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. Are package dependencies listed with build order?
  4. Does the spec reference existing patterns (Cathedral Check)?
  5. Are edge cases listed with expected behavior?
  6. Is the model requirement appropriate for the complexity?

Governance​

Specs are version-controlled alongside the code they describe. The guidance consistency check (node .claude/scripts/check-guidance-consistency.js) validates that specs do not contradict the rules and constraints defined in CLAUDE.md and .claude/rules/.

Next page

Next best action

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

Claude Code