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:

Agent	Purpose	Model
cracked-coder	Feature implementation with TDD	Opus
oracle	Architecture guidance and analysis	Opus

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 (.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 `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

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 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. 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 Claude guidance check (node .claude/scripts/check-skill-frontmatter.js) validates skill frontmatter, the skills registry, command routes, bundles, and retired guidance surfaces. It does not prove that specs semantically agree with every rule, 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

• Intent Engineering
• Codex