plan - SKILL.md Agent Skill

name: plan description: Phase D of greenfield project bootstrap. Produce design.md + data-model.md + contracts/{openapi,asyncapi,schemas/} + adr/NNNN-.md. Validates contracts via swagger-cli/asyncapi/ajv before exit. disable-model-invocation: true allowed-tools: Read, Write, Edit, Bash, Glob

/plan — design + contracts + ADRs

After /constitute locked in non-negotiables, this skill produces the technical design that workers will implement.

Artifacts to produce

spec/001-<slug>/design.md — architecture overview, sequence diagrams (mermaid), error handling strategy
spec/001-<slug>/data-model.md — entities, relationships, persistence shape
spec/001-<slug>/contracts/openapi.yaml — sync API contracts (HTTP endpoints)
spec/001-<slug>/contracts/asyncapi.yaml — event contracts (queues/topics)
spec/001-<slug>/contracts/schemas/*.json — shared JSON Schema for data shapes
adr/NNNN-<decision>.md — one MADR file per arguable architectural choice

Templates

<bootstrap-pack>/templates/{design.md,data-model.md,openapi.yaml,asyncapi.yaml,adr-0001-record-architecture-decisions.md}.tmpl

Validation

Before exit, run:

# Each contracts file must parse
npx swagger-cli validate spec/001-*/contracts/openapi.yaml
npx @asyncapi/cli validate spec/001-*/contracts/asyncapi.yaml
for f in spec/001-*/contracts/schemas/*.json; do
  npx ajv-cli compile -s "$f"
done

# Validator-gate checks
<bootstrap-pack>/scripts/validate-project-spec.py . --check openapi_valid
<bootstrap-pack>/scripts/validate-project-spec.py . --check asyncapi_valid
<bootstrap-pack>/scripts/validate-project-spec.py . --check json_schemas_valid
<bootstrap-pack>/scripts/validate-project-spec.py . --check adr_exists

If any contract fails to parse, iterate until clean.

ADR criteria

Write an ADR for any choice the operator (or a future contributor) might argue about in 6 months:

Database choice (Postgres vs Mongo vs SQLite)
Auth mechanism (JWT vs OAuth2 vs mTLS)
Message bus (NATS vs Kafka vs Redis Streams)
Frontend framework
Deployment target (K8s vs containers-on-VMs vs serverless)
Significant library choice with alternatives

Each ADR has: Status, Context, Decision, Consequences (positive + negative), Alternatives considered.

Definition of done

All 6 artifact categories exist
All contract files parse cleanly
At least one ADR exists (always include ADR-0001 from template)
Operator has skimmed design.md + reviewed top-level architecture

What's next

Operator runs /tasks to atomize the design into the work_units that parallel-dev workers will execute.