papadopouloskyriakos/agentic-chatops/plan

/plan — design + contracts + ADRs

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

Artifacts to produce

1. spec/001-<slug>/design.md — architecture overview, sequence diagrams (mermaid), error handling strategy
2. spec/001-<slug>/data-model.md — entities, relationships, persistence shape
3. spec/001-<slug>/contracts/openapi.yaml — sync API contracts (HTTP endpoints)
4. spec/001-<slug>/contracts/asyncapi.yaml — event contracts (queues/topics)
5. spec/001-<slug>/contracts/schemas/*.json — shared JSON Schema for data shapes
6. 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.