anycrew 0.0.0-stage → 0.1.0

package/templates/docs/04-requirements-traceability.md

@@ -0,0 +1,9 @@
+# 04 — Requirements traceability
+
+> One row per requirement. The spec-writer fills the spec column; the tester fills the test column;
+> evidence is a report, a screenshot or a recorded run with a date.
+
+| Requirement | Priority | Spec | Test(s) | Evidence |
+|---|---|---|---|---|
+| FR-001 | P0 | | | |
+| NFR-001 | P0 | | | |

package/templates/docs/05-architecture.md

@@ -0,0 +1,35 @@
+# 05 — Architecture
+
+> Containers, flows and boundaries. Decisions that are expensive to reverse are in [`adr/`](adr/README.md).
+
+## 1. Context
+```mermaid
+flowchart LR
+  user["User"] --> app["{{project}}"]
+  app --> ext["External systems"]
+```
+## 2. Containers
+| Container | Responsibility | Runs where | Talks to |
+|---|---|---|---|
+## 3. Critical flows
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant A as API
+  U->>A: request
+  A-->>U: response
+```
+## 4. Boundaries and layers
+| Layer | May import | Must not |
+|---|---|---|
+## 5. State, jobs and idempotency
+## 6. Limits and quotas
+| Limit | Value | Enforced where |
+|---|---|---|
+## 7. Regions, residency and environments
+## 8. Constitution check
+| Principle | How the design satisfies it |
+|---|---|
+## 9. Specs to write, in build order
+| # | Spec | Depends on |
+|---|---|---|

package/templates/docs/06-agent-design.md

@@ -0,0 +1,25 @@
+# 06 — Agent design
+
+> The model-backed parts of the product: where a model is used, where code decides, every call's
+> contract, guardrails and evals. Rule: `.agents/rules/50-llm-features.md`.
+
+## 1. Model / code boundary
+| Step | Needs | Done by | Why |
+|---|---|---|---|
+| | judgement / correctness | model (tier) / code | |
+## 2. Calls
+| Call | Purpose | Inputs (untrusted marked) | Output schema | Tier | Temp | Timeout / retry / fallback | Cost per call |
+|---|---|---|---|---|---|---|---|
+## 3. Prompts
+Prompts live in `{{prompts_dir}}` with front matter `id`, `version`, `model`, `output_schema`.
+## 4. Guardrails
+- Untrusted content framing; tool permissions; output validation; grounding and citations.
+## 5. Orchestration (if multi-agent)
+```mermaid
+flowchart TB
+  a["step 1 (code)"] --> b["step 2 (model, fast)"] --> c["step 3 (code)"]
+```
+## 6. Evals
+| Eval | Dataset | Scorer | Last result (date) |
+|---|---|---|---|
+## 7. Tracing and cost

package/templates/docs/09-data-model.md

@@ -0,0 +1,17 @@
+# 09 — Data model
+
+## 1. Entities
+| Entity | Owner / tenancy | ID scheme | Lifecycle states |
+|---|---|---|---|
+## 2. Diagram
+```mermaid
+erDiagram
+  WORKSPACE ||--o{ ITEM : has
+```
+## 3. State machines
+| Entity | From | Event | To | Side effects |
+|---|---|---|---|---|
+## 4. Indexes and queries
+## 5. Versioning and migrations
+Every stored record carries a schema version; breaking changes go expand → migrate → contract.
+## 6. Retention and deletion

package/templates/docs/10-api-contract.md

@@ -0,0 +1,13 @@
+# 10 — API contract
+
+> The machine-readable contract (`{{contracts_dir}}/openapi.yaml`) is authoritative; this page explains it.
+
+## 1. Conventions
+- Auth, versioning, pagination, idempotency keys, time and money formats.
+## 2. Resources
+| Resource | Endpoints | Notes |
+|---|---|---|
+## 3. Errors
+| Code | HTTP | When |
+|---|---|---|
+## 4. Limits

package/templates/docs/11-frontend.md

@@ -0,0 +1,18 @@
+# 11 — Frontend
+
+## 1. Information architecture
+## 2. Routes
+| Path | Purpose | Data | Who can see it |
+|---|---|---|---|
+## 3. Screen flow
+```mermaid
+flowchart LR
+  home["/"] --> detail["/items/:id"]
+```
+## 4. Screens
+### <screen>
+- **Words:** title, labels, actions.
+- **States:** loading, empty, error, success.
+- **Responsive:** 360–599 / 600–1023 / 1024–1600 px behaviour.
+## 5. Realtime and caching
+## 6. Accessibility

package/templates/docs/12-design-system.md

@@ -0,0 +1,14 @@
+# 12 — Design system
+
+## 1. Principles and what we avoid
+## 2. Tokens
+Source of truth: `{{contracts_dir}}/design/tokens.json`. Colour roles, type scale, spacing, radius,
+elevation, motion, breakpoints. Contrast pairs checked against WCAG AA.
+## 3. Layout and window classes
+## 4. Components
+| Component | Variants | States |
+|---|---|---|
+## 5. Content style
+## 6. Quality gates
+| Gate | Tool | Fails when |
+|---|---|---|

package/templates/docs/13-conventions.md

@@ -0,0 +1,26 @@
+# 13 — Conventions
+
+> How code is organised and written so that every feature looks like it was written by one person.
+> Coding agents follow this page through `.agents/rules/`.
+
+## 1. Repository layout
+```
+{{layout_sketch}}
+```
+## 2. Layers and allowed imports
+| Layer | May import | Must not |
+|---|---|---|
+Enforced by: <tool> in `{{check_cmd}}`.
+## 3. Patterns we use, and where
+| Pattern | Where | Why |
+|---|---|---|
+| Ports & adapters | | swap external systems for fakes |
+| Composition root | | no globals |
+| Policy as configuration | | reviewable rules |
+## 4. Language conventions
+<!-- Filled from the preset; edit freely. -->
+{{backend_conventions}}
+
+{{frontend_conventions}}
+## 5. Git conventions
+- Branch per spec; commit `feat(NNN): …` with `Tasks:` and `AC:` trailers; one task per commit.

package/templates/docs/14-security.md

@@ -0,0 +1,23 @@
+# 14 — Security
+
+## 1. Assets and actors
+## 2. Trust boundaries
+```mermaid
+flowchart LR
+  subgraph untrusted
+    u["User / uploads / model output"]
+  end
+  subgraph trusted
+    api["API"] --> db["Data"]
+  end
+  u --> api
+```
+## 3. Controls
+| ID | Boundary | Control | Proven by (test) |
+|---|---|---|---|
+| C1 | | | |
+## 4. Data protection
+## 5. Dependencies and supply chain
+## 6. Residual risks
+| Risk | Accepted by | Date | Revisit |
+|---|---|---|---|

package/templates/docs/15-testing.md

@@ -0,0 +1,18 @@
+# 15 — Testing
+
+> Tests prove the code does what the spec says. Evals measure how well models do their part. Tests
+> gate merges; evals inform decisions.
+
+## 1. Layers
+| Layer | What | Runs | Gate? | Location |
+|---|---|---|---|---|
+| Unit | | every `{{check_cmd}}` | ✔ | |
+| Integration | | every `{{check_cmd}}` | ✔ | |
+| Scenario / E2E | | | | |
+| Contract | | | ✔ | |
+| Visual / a11y | | | | |
+| Evals | real models, on demand | | ✘ | |
+Coverage floors: domain ≥ 90 %, services ≥ 80 % (floors, not goals).
+## 2. Gates per change
+## 3. Ground truth and fixtures
+## 4. Evals

package/templates/docs/16-infrastructure.md

@@ -0,0 +1,17 @@
+# 16 — Infrastructure & deployment
+
+## 1. Environments
+| Environment | Purpose | Differences |
+|---|---|---|
+## 2. Build
+## 3. Pipeline
+## 4. Configuration
+| Variable | Purpose | Default | Secret? |
+|---|---|---|---|
+## 5. Deploy
+```bash
+{{deploy_cmd}}
+```
+## 6. Roll back
+## 7. Cost guardrails
+## 8. Runbook

package/templates/docs/17-observability.md

@@ -0,0 +1,8 @@
+# 17 — Observability
+
+## 1. Logs (structured, correlation IDs, what is never logged)
+## 2. Traces (one per request or job; spans per external call)
+## 3. Metrics (latency, traffic, errors, saturation; cost)
+## 4. Alerts
+| Alert | Condition | Owner | Runbook |
+|---|---|---|---|

package/templates/docs/19-delivery-plan.md

@@ -0,0 +1,10 @@
+# 19 — Delivery plan
+
+## 1. Roles
+| Role | Owns | Person |
+|---|---|---|
+## 2. Milestones
+| Day / week | Deliverable | Specs | Done when |
+|---|---|---|---|
+## 3. Cut line
+## 4. Definition of done (release)

package/templates/docs/20-implementation-status.md

@@ -0,0 +1,18 @@
+# 20 — Implementation status
+
+> What is actually built. Updated in the **same commit** as any change that adds, completes or
+> removes a component. Statuses: **Specified** → **In progress** → **Built** (tests green, suite
+> named) → **Deployed** · **Partial** (built without a test that would catch a regression) ·
+> **Cut** (deliberately dropped, with reason).
+
+_Last updated: {{date}} — initialised by anycrew._
+
+## Components
+
+| Component | Spec | Status | Notes (tests, deviations) |
+|---|---|---|---|
+| Repository, docs skeleton, agent guide | — | Built | `npx anycrew init` |
+
+## Gaps
+
+- None recorded yet.

package/templates/docs/README.md

@@ -0,0 +1,34 @@
+# {{project}} documentation
+
+Specifications are the source of truth: code implements them, and both change together.
+
+## Reading order
+
+**For a new teammate:** 00 → 01 → 03 → 05 → 13 → 20.
+**For a coding agent starting a spec:** `AGENTS.md` → 00 → the spec folder → the docs it links.
+
+| # | Document | Answers |
+|---|---|---|
+| 00 | [Constitution](00-constitution.md) | The principles every change is checked against |
+| 01 | [Brainstorm & decision](01-brainstorm-and-decision.md) | Which idea, why, what is out of scope, the name |
+| 02 | [Research](02-research.md) | Verified facts with sources; spikes |
+| 03 | [PRD](03-prd.md) | Users, journeys, P0/P1/P2 scope, FR/NFR |
+| 04 | [Requirements traceability](04-requirements-traceability.md) | FR → spec → test → evidence |
+| 05 | [Architecture](05-architecture.md) | Containers, flows, boundaries, limits |
+| 06 | [Agent design](06-agent-design.md) | Model-backed steps, prompts, guardrails, evals (if any) |
+| 09 | [Data model](09-data-model.md) | Entities, IDs, states, indexes, migrations |
+| 10 | [API contract](10-api-contract.md) | Endpoints, errors, auth, limits (YAML in `contracts/`) |
+| 11 | [Frontend](11-frontend.md) | Routes, screens, states, flows, responsive rules |
+| 12 | [Design system](12-design-system.md) | Tokens, type, layout, components, content style, gates |
+| 13 | [Conventions](13-conventions.md) | Layout, layers, patterns, coding and git conventions |
+| 14 | [Security](14-security.md) | Threat model, controls, data protection |
+| 15 | [Testing](15-testing.md) | Test layers, gates, ground truth, evals |
+| 16 | [Infrastructure & deployment](16-infrastructure.md) | Environments, config, pipeline, runbook |
+| 17 | [Observability](17-observability.md) | Logs, traces, metrics, alerts, cost |
+| 19 | [Delivery plan](19-delivery-plan.md) | Roles, milestones, cut line, definition of done |
+| 20 | [Implementation status](20-implementation-status.md) | What is actually built |
+| — | [Glossary](glossary.md) | Terms |
+| — | [ADRs](adr/README.md) | Decisions and their trade-offs |
+| — | [Specs](specs/README.md) | Feature specs: spec → plan → tasks, build order |
+
+Documents are created when a phase needs them; a missing number means the phase has not run.

package/templates/docs/adr/ADR-template.md

@@ -0,0 +1,13 @@
+# ADR-NNN — <title>
+
+**Status:** Proposed / Accepted / Superseded by ADR-… · **Date:** · **Deciders:**
+
+## Context
+## Options considered
+| Option | What it costs | What it gives |
+|---|---|---|
+## Decision
+## Consequences
+- Good:
+- Bad:
+## How to revisit

package/templates/docs/adr/README.md

@@ -0,0 +1,4 @@
+# Decisions (ADRs)
+
+| ADR | Decision | Status |
+|---|---|---|

package/templates/docs/glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+| Term | Meaning |
+|---|---|
+| AC-NNN-n | Acceptance criterion n of spec NNN |
+| TNNN-nn | Task nn of spec NNN |
+| FR / NFR | Functional / non-functional requirement |
+| ADR | Architecture decision record |

package/templates/docs/specs/NNN-template/plan.md

@@ -0,0 +1,25 @@
+# Plan NNN — <Title>
+
+## Approach
+<!-- The thinnest vertical slice first; breadth after depth. -->
+
+## Slice 1 — <name> (proves: <which risk it retires>)
+| # | Change | File(s) | Depends on |
+|---|---|---|---|
+**Done when:** <observable, testable condition>
+
+## Slice 2 — …
+
+## Contract and data changes
+- `{{contracts_dir}}/openapi.yaml`: …
+- Data model: … (migration steps if breaking)
+
+## Dependencies
+| Package | Version | Why |
+|---|---|---|
+
+## Constitution check
+| Principle | ✔ / conflict and how resolved |
+|---|---|
+
+## Risks and open questions

package/templates/docs/specs/NNN-template/spec.md

@@ -0,0 +1,26 @@
+# Spec NNN — <Title>
+
+| | |
+|---|---|
+| **Status** | Draft / Ready |
+| **Priority** | P0 / P1 / P2 |
+| **Owner** | |
+| **Depends on** | |
+| **Requirements** | FR-…, NFR-… |
+| **Design** | links to docs/05, 09, 10, 11 sections |
+
+## Summary
+
+## User stories
+
+### US-NNN-1: <story>
+- **AC-NNN-1** Given …, when …, then …
+- **AC-NNN-2** Given …, when …, then …
+
+## Out of scope
+
+## Edge cases
+
+## Change log
+| Date | Change | Why |
+|---|---|---|

package/templates/docs/specs/NNN-template/tasks.md

@@ -0,0 +1,14 @@
+# Tasks NNN — <Title>
+
+## Slice 1
+
+- [ ] **TNNN-01** **TDD** <behaviour>: test `<path::name>`, then the smallest change in `<file>`. (AC-NNN-1)
+- [ ] **TNNN-02** <change> in `<file>`. (AC-NNN-2)
+
+## Slice 2
+
+- [ ] **TNNN-03** …
+
+## Close
+
+- [ ] **TNNN-99** Update `docs/20-implementation-status.md` (name the suite that covers each AC).

package/templates/docs/specs/README.md

@@ -0,0 +1,25 @@
+# Specs
+
+Each folder is one feature, written spec-first: **`spec.md`** (what and why, with acceptance
+criteria) → **`plan.md`** (how, which files) → **`tasks.md`** (ordered, test-first checklist).
+
+## Index and build order
+
+| # | Spec | Priority | Depends on | Status |
+|---|---|---|---|---|
+
+```mermaid
+flowchart TB
+  s001["001 foundation"]
+```
+
+## How a coding agent works a spec
+
+1. Read `AGENTS.md`, then the spec's `spec.md`, `plan.md` and every doc they link.
+2. Take the first unchecked task in `tasks.md`. For **TDD** tasks, write the failing test first.
+3. Implement the smallest change that makes it pass; run `{{check_cmd}}`.
+4. Tick the task, commit `feat(NNN): …` with `Tasks: TNNN-nn` in the body.
+5. If the spec is wrong or unclear, stop and propose a spec change. Do not silently diverge.
+6. When the spec's tasks are done, update `docs/20-implementation-status.md`.
+
+The `/crew-spec`, `/crew-implement` and `/crew-verify` skills encode this loop.