@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/rules/data-format-convention.md

@@ -1,136 +1,74 @@
----
-name: data-format-convention
-description: Which file format to use when producing or consuming structured data — YAML for agent-readable reference data, Markdown for narrative, JSON for machine-consumed data
-priority: 8
-version: 1.0.0
----
-
-# Data Format Convention
-
-Use the right format for the right consumer. The same data structure reads very differently depending on who (or what) will consume it next.
-
-## The three formats and their consumers
-
-### YAML — structured data consumed by agents
-
-Use `.yaml` when the output is structured reference data that **another agent or squad executor will read field-by-field** to make decisions or produce content.
-
-LLMs read YAML more accurately than JSON for structured reference data because YAML allows comments, avoids excessive punctuation, and mirrors natural document structure.
-
-**Use YAML for:**
-- ICP definitions, persona profiles, audience segments
-- Offer sheets, product definitions, pricing structures
-- Brand guidelines (structured parts: tone, values, vocabulary, positioning)
-- Competitive analysis snapshots (structured fields)
-- Briefing data that a copy squad or design squad will consume
-- Entity catalogs referenced across multiple sessions
-
-**Naming:** `{slug}.yaml` in the relevant squad output or context directory.
-
-**Example — ICP profile (`icp-primary.yaml`):**
-```yaml
-# ICP — Primary Audience
-# Created by: @research-squad | Updated: 2026-04-02
-
-profile:
-  name: "Empreendedor Refém"
-  description: "Dono de negócio que depende de agências ou devs externos"
-
-pain_points:
-  - Perda de controle sobre o produto
-  - Atrasos e custos imprevisíveis
-  - Não consegue validar qualidade do que recebe
-
-desired_outcome: "Autonomia e velocidade — entregar sem depender de terceiros"
-
-buying_trigger: "Prazo vencendo ou fatura chegando de dev que atrasou"
-
-messaging:
-  primary: "Retome o controle do seu produto"
-  objection_1: "Não preciso saber programar?"
-  objection_1_answer: "Não. Você vai orquestrar, não digitar código."
-
-channels: [instagram, linkedin, youtube]
-```
-
----
-
-### Markdown — narrative content consumed by humans and agents linearly
-
-Use `.md` when the output is narrative — content that flows as text and benefits from headers, lists, and prose.
-
-**Use Markdown for:**
-- Reports, analyses, article drafts
-- Scripts, hooks, copy blocks
-- Agent instructions and rules (this file is an example)
-- Specs, PRDs, discovery documents
-- Any output meant to be read from top to bottom
-
-**Never use YAML or JSON for:** articles, scripts, agent instructions, PRDs, analysis narratives, README files.
-
----
-
-### JSON — structured data consumed by machines
-
-Use `.json` when the output is consumed by code — CLIs, APIs, webhooks, dashboards, or configuration parsers.
-
-**Use JSON for:**
-- `squad.manifest.json` — consumed by the AIOSON CLI and dashboard
-- `content.json` — consumed by the webhook server and dashboard
-- API payloads and webhook responses
-- CLI configuration files
-- Any file that `JSON.parse()` will read programmatically
-
-**Never change to YAML:** `squad.manifest.json`, `content.json`, `squad.json`, `aioson-models.json`. These are machine-consumed and must stay JSON for CLI compatibility.
-
----
-
-## Decision rule (apply in this order)
-
-```
-Will a machine (CLI, API, webhook, dashboard) consume this file?
-  YES → JSON
-
-Will a human or agent read this top-to-bottom as narrative?
-  YES → Markdown
-
-Will an agent reference specific fields to make decisions or produce content?
-  YES → YAML
-```
-
-If uncertain: prefer Markdown. Only use YAML when the structured fields are the point — not the prose.
-
----
-
-## Squad executor guidance
-
-When a squad executor produces output, choose the format based on what happens next:
-
-| Output type | Format | Example |
-|---|---|---|
-| Report, article, script | `.md` | `output/content-squad/ep-001/script.md` |
-| ICP, persona, audience profile | `.yaml` | `output/research-squad/icp-primary.yaml` |
-| Brand data, offer sheet | `.yaml` | `output/brand-squad/offer-advanced.yaml` |
-| Competitive analysis (structured) | `.yaml` | `output/research-squad/competitors.yaml` |
-| Competitive analysis (narrative) | `.md` | `output/research-squad/market-report.md` |
-| Webhook payload, API response | `.json` | handled by `content.json` convention |
-| Squad manifest, config | `.json` | `squad.manifest.json` (do not change) |
-
-**Cross-squad consumption:** when Squad A produces data that Squad B will consume, prefer YAML for structured reference data. The receiving squad's executor can reference `output/squad-a/{file}.yaml` directly and access fields with precision — more reliable than parsing a Markdown table.
-
----
-
-## What NOT to change
-
-- Files with `.json` extension consumed by the AIOSON CLI or dashboard
-- Agent instruction files (`agents/*.md`) — narrative, not data
-- Existing specs and context files (`spec-*.md`, `discovery.md`, `architecture.md`) — mixed narrative + structure, Markdown is correct
-- YAML frontmatter inside `.md` files — this is already the right pattern for metadata
-
----
-
-## Why this matters
-
-The same structured content stored as JSON or Markdown loses precision when an agent reads it. A JSON blob requires the agent to mentally parse brackets and quotes while tracking field relationships. A Markdown table requires the agent to infer column semantics from headers. A YAML document makes field names, nesting, and relationships immediately legible — the LLM spends its attention on the content, not the syntax.
-
-For squads that pass structured data between executors across sessions, this compounds: each session starts fresh, and a YAML profile loads faster and more accurately into working context than an equivalent JSON or Markdown representation.
+---
+name: data-format-convention
+description: Which file format to use when producing or consuming structured data — YAML for agent-readable reference data, Markdown for narrative, JSON for machine-consumed data
+priority: 8
+version: 1.0.0
+---
+
+# Data Format Convention
+
+## Decision rule (apply in order)
+
+```
+Will a machine (CLI, API, webhook, dashboard) consume this? → JSON
+Will human/agent read top-to-bottom as narrative?          → Markdown
+Will an agent reference specific fields to make decisions? → YAML
+```
+
+If uncertain: prefer Markdown. Only use YAML when structured fields are the point.
+
+## The three formats
+
+### YAML — structured data for agent field-by-field consumption
+
+LLMs read YAML more accurately than JSON for reference data (comments allowed, less punctuation).
+
+Use for: ICP profiles, persona profiles, audience segments, offer sheets, pricing structures, brand guidelines (structured parts), competitive analysis (structured), briefing data for copy/design squads.
+
+**Example (`icp-primary.yaml`):**
+```yaml
+profile:
+  name: "Empreendedor Refém"
+  description: "Dono de negócio que depende de agências ou devs externos"
+pain_points:
+  - Perda de controle sobre o produto
+  - Atrasos e custos imprevisíveis
+desired_outcome: "Autonomia e velocidade"
+buying_trigger: "Prazo vencendo ou fatura chegando de dev que atrasou"
+messaging:
+  primary: "Retome o controle do seu produto"
+channels: [instagram, linkedin, youtube]
+```
+
+### Markdown — narrative for humans and linear agent reading
+
+Use for: reports, analyses, article drafts, scripts, agent instructions, specs, PRDs, discovery docs, README files, any output read top-to-bottom.
+
+Never use YAML or JSON for: articles, scripts, agent instructions, PRDs, analysis narratives.
+
+### JSON — structured data for machine consumption
+
+Use for: `squad.manifest.json`, `content.json`, API payloads, webhook responses, CLI config files.
+
+Never change to YAML: `squad.manifest.json`, `content.json`, `squad.json`, `aioson-models.json` — machine-consumed, must stay JSON for CLI compatibility.
+
+## Squad executor output format
+
+| Output type | Format | Example |
+|---|---|---|
+| Report, article, script | `.md` | `output/content-squad/ep-001/script.md` |
+| ICP, persona, audience profile | `.yaml` | `output/research-squad/icp-primary.yaml` |
+| Brand data, offer sheet | `.yaml` | `output/brand-squad/offer-advanced.yaml` |
+| Competitive analysis (structured) | `.yaml` | `output/research-squad/competitors.yaml` |
+| Competitive analysis (narrative) | `.md` | `output/research-squad/market-report.md` |
+| Webhook payload, API response | `.json` | handled by `content.json` convention |
+| Squad manifest, config | `.json` | `squad.manifest.json` (do not change) |
+
+**Cross-squad consumption:** when Squad A produces data for Squad B, prefer YAML for structured reference — more reliable than parsing a Markdown table.
+
+## What NOT to change
+
+- `.json` files consumed by AIOSON CLI or dashboard
+- Agent instruction files (`agents/*.md`) — narrative, not data
+- Existing specs and context files — Markdown is correct
+- YAML frontmatter inside `.md` files

package/template/.aioson/rules/disk-first-artifacts.md

@@ -0,0 +1,44 @@
+---
+name: disk-first-artifacts
+description: Todo artefato gerado por um agente deve ser gravado em disco antes do fim da sessão — nunca apenas exibido no chat
+priority: 10
+version: 1.0.0
+---
+
+# Disk-First: Artifacts Always on Disk
+
+Every artifact produced by an AIOSON agent MUST be written to disk before session end. Showing in chat does not count as delivery — the next agent starts without context and the work is lost.
+
+## Mandatory artifacts by agent
+
+| Agent | Mandatory artifact | Path |
+|---|---|---|
+| `@product` | PRD | `.aioson/context/prd.md` or `prd-{slug}.md` |
+| `@product` | features.md | `.aioson/context/features.md` |
+| `@analyst` | Discovery | `.aioson/context/discovery.md` |
+| `@analyst` | Requirements | `.aioson/context/requirements-{slug}.md` |
+| `@architect` | Architecture | `.aioson/context/architecture.md` |
+| `@ux-ui` | UI Spec | `.aioson/context/ui-spec-{slug}.md` |
+| `@sheldon` | Manifest | `.aioson/plans/{slug}/manifest.md` |
+| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
+| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
+| `@qa` | QA report | `.aioson/context/qa-report-{slug}.md` |
+| `@squad` | Squad manifest | `.aioson/squads/{slug}/squad.manifest.json` |
+| `@squad` | Agent prompts | `.aioson/squads/{slug}/agents/{agent}.md` |
+
+## Correct delivery pattern
+
+```
+✅ Write artifact to disk → inform user of path.
+❌ Show in chat → ask "Can I save?" → Do NOT do this.
+```
+
+Exceptions: drafts shown mid-session for validation (before final save), artifacts explicitly cancelled by user.
+
+`project-pulse.md` must be updated at session end regardless of other artifacts.
+
+## On violation detected
+
+1. Write the artifact before closing — never defer to next session.
+2. If content was shown in chat, use it to write the file now.
+3. Update `project-pulse.md`.

package/template/.aioson/rules/example-monetary-values.md

@@ -1,30 +1,30 @@
----
-name: monetary-values
-description: All monetary values must be stored as integer cents, never as floats
-agents: [dev, architect, qa]
-priority: 5
-version: 1.0.0
----
-
-# Monetary Values Convention
-
-All monetary values in this project MUST be stored and calculated as integer cents.
-
-## Rule
-
-- NEVER use float or decimal types for money fields
-- Store as integer: `1000` = R$ 10,00 or USD $10.00
-- Display formatting is a UI concern only — format at the presentation layer, never in persistence or business logic
-- This applies to: database columns, API payloads, internal calculations, test fixtures
-
-## Rationale
-
-Float arithmetic produces rounding errors in financial calculations.
-Example: `0.1 + 0.2 === 0.30000000000000004` in most languages.
-Using integer cents eliminates this class of bug entirely.
-
-## Applies to
-
-- Database migrations: column type must be integer or bigint, not decimal/float
-- API contracts: monetary fields must be documented as integer cents
-- @qa: test fixtures must use integer cents; any float in a money field is a bug
+---
+name: monetary-values
+description: All monetary values must be stored as integer cents, never as floats
+agents: [dev, architect, qa]
+priority: 5
+version: 1.0.0
+---
+
+# Monetary Values Convention
+
+All monetary values in this project MUST be stored and calculated as integer cents.
+
+## Rule
+
+- NEVER use float or decimal types for money fields
+- Store as integer: `1000` = R$ 10,00 or USD $10.00
+- Display formatting is a UI concern only — format at the presentation layer, never in persistence or business logic
+- This applies to: database columns, API payloads, internal calculations, test fixtures
+
+## Rationale
+
+Float arithmetic produces rounding errors in financial calculations.
+Example: `0.1 + 0.2 === 0.30000000000000004` in most languages.
+Using integer cents eliminates this class of bug entirely.
+
+## Applies to
+
+- Database migrations: column type must be integer or bigint, not decimal/float
+- API contracts: monetary fields must be documented as integer cents
+- @qa: test fixtures must use integer cents; any float in a money field is a bug

package/template/.aioson/rules/output-brevity.md

@@ -0,0 +1,44 @@
+---
+name: output-brevity
+description: All agents must produce terse, direct output — no preambles, no trailing summaries, no narration of actions
+priority: 8
+version: 1.0.0
+---
+
+# Output Brevity
+
+All agents produce direct output. No padding.
+
+## What to eliminate
+
+- Preambles: "I will now...", "Let me...", "I'm going to..."
+- Trailing summaries: "In summary, I have...", "To recap what was done..."
+- Action narration: "Reading the file...", "Now I'll check..."
+- Filler acknowledgements: "Great!", "Sure!", "Of course!", "Absolutely!"
+- Restating the user's request before answering it
+
+## What to keep
+
+- Artifact content — complete and uncompressed
+- Technical explanations when genuinely non-obvious
+- Questions when clarification is required
+- Security warnings, irreversible action confirmations — revert to full prose for these
+
+## Pattern
+
+```
+❌  "I'll analyze the project structure and then provide my findings..."
+✅  [analysis output directly]
+
+❌  "In summary, I've created 3 files and updated the spec."
+✅  "Created: spec-auth.md, prd-auth.md, features.md"
+
+❌  "Great question! Let me explain how this works..."
+✅  [explanation directly]
+```
+
+## Exceptions — use full prose
+
+- Security warnings or destructive action confirmations
+- Multi-step sequences where brevity would cause ambiguity
+- User appears confused or has contradictory requirements

package/template/.aioson/rules/prd-section-ownership.md

@@ -0,0 +1,49 @@
+---
+name: prd-section-ownership
+description: Define qual agente é dono de cada seção do PRD — outros agentes não podem modificar seções que não são suas
+priority: 9
+version: 1.0.0
+agents: [product, pm, analyst, architect, ux-ui, sheldon]
+---
+
+# PRD Section Ownership
+
+`prd.md` and `prd-{slug}.md` are shared documents. Each section has one owner — others may only read or append sub-sections, never replace.
+
+## Ownership table
+
+| PRD Section | Owner | Others may |
+|---|---|---|
+| `## Objetivo` | `@product` | Read only |
+| `## Problema` | `@product` | Read only |
+| `## Usuários e Personas` | `@product` | Read only |
+| `## Funcionalidades` | `@product` | Read only |
+| `## Critérios de Aceite` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
+| `## Fases de Entrega` | `@pm` | Read only |
+| `## Restrições Técnicas` | `@architect` | Read only |
+| `## Considerações de UX` | `@ux-ui` | Read only |
+| `## Riscos` | `@pm` | `@analyst`, `@architect` add new risks only |
+| `## Decisões Registradas` | `@sheldon` (project) / `@pm` (feature) | Read only |
+
+## Modification rule
+
+An agent may only modify sections it owns. Non-owners may only **add** a new sub-section at the end — never replace or rewrite existing content.
+
+## Safe addition pattern
+
+```markdown
+## Critérios de Aceite
+<!-- @product: owner of this section -->
+
+- CA-01: User can schedule an appointment
+- CA-02: System sends confirmation email
+
+### Technical criteria (added by @analyst)
+- CA-T01: Scheduling validates availability via DB query before confirming
+- CA-T02: Email queue uses BullMQ with 3x retry
+```
+
+## On violation detected
+
+1. Do not overwrite the section.
+2. Create a sub-section with explicit attribution (`<!-- added by @{agent} -->`), OR create a separate artifact (`requirements-{slug}.md`, `architecture.md`, etc.).

package/template/.aioson/rules/security-baseline.md

@@ -0,0 +1,139 @@
+---
+name: security-baseline
+description: Secure by Default baseline controls for technical agents
+priority: 10
+version: 1.0.0
+agents: [analyst, architect, dev, qa]
+---
+
+# Security Baseline — Secure by Default
+
+> Implements `Article VII — Zero Trust by Default` of the AIOSON constitution.
+> Loaded by `@analyst`, `@architect`, `@dev`, and `@qa`. Other agents must not
+> load this rule — product, copy, design and orchestration scopes are out of band.
+
+This rule defines the minimum security baseline every technical agent must
+respect. It does **not** promise absolute security. It declares concrete
+controls, expected evidence and how each project classification consumes them.
+Deviations are allowed only when recorded as an explicit decision in the
+feature `spec-{slug}.md` with N/A rationale.
+
+## Classification policy
+
+| Classification | Behavior |
+|---|---|
+| **MICRO** | **Advisory.** Controls are surfaced as recommendations. No automated blocking. `@qa` may still flag obviously dangerous patterns. |
+| **SMALL** | **Scan-oriented.** Static checks and tool-first scans run automatically. `@pentester` is **not** mandatory. Open Medium+ findings are reported but do not block by default. |
+| **MEDIUM** | **Audit-blocking.** Surface assessment runs against attack-surface map. **Open High or Critical findings block Gate D** until resolved or explicitly waived with rationale recorded in `spec-{slug}.md`. |
+
+`@pentester` (`app_target` mode) may be invoked by `@qa` for any feature with
+auth, money, ownership, file uploads, external URLs or suspicious audit
+findings — regardless of classification. It is never required by classification
+alone.
+
+## Severity scale
+
+| Severity | Examples |
+|---|---|
+| `critical` | Ownership bypass, financial race condition, committed production secret. |
+| `high` | Missing server-side validation, unsafe upload signature handling, missing rate limit on sensitive endpoint. |
+| `medium` | Unsanitized external URL, low-impact tracker, storage boundary abuse surface. |
+| `advisory` | MICRO recommendations or surfaces marked N/A with explicit rationale. |
+
+## Direct LLM mode (no CLI)
+
+When the `aioson` CLI is unavailable, agents must fall back to **checklist-only
+verification** of the controls below, record the limitation in the session
+devlog, and **must not** fabricate runtime telemetry events. Findings still
+land in `.aioson/context/security-findings-{slug}.json` (one of the few
+machine-readable exceptions allowed under `.aioson/context/`).
+
+## Controls
+
+### SEC-SBD-01 — Server-side input limits
+
+- Maps to: OWASP A03 / A04
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@analyst` (declares limits), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts user input
+- Required evidence: explicit field-length / type / range limits enforced server-side, plus negative tests asserting rejection on overflow or wrong type. N/A rationale required when feature has no user input.
+
+### SEC-SBD-02 — Upload file signature validation
+
+- Maps to: OWASP A03 / A05
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts uploads
+- Required evidence: magic-byte / file-signature validation independent of MIME header and extension; rejection test for spoofed extension. N/A when no upload surface exists.
+
+### SEC-SBD-03 — Ownership / IDOR authorization
+
+- Maps to: OWASP A01
+- Default severity: `critical`
+- Owner agent: `@dev` (implements), `@analyst` (maps surfaces), `@qa` (verifies)
+- Applies to: analyst, architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on every endpoint that returns or mutates per-user data
+- Required evidence: ownership check at the data layer (not only route), and a negative test where user A attempts to access user B's resource and receives 403/404. N/A only when resource is intentionally public.
+
+### SEC-SBD-04 — Atomic critical state changes
+
+- Maps to: OWASP A04
+- Default severity: `critical`
+- Owner agent: `@architect` (designs), `@dev` (implements), `@qa` (verifies)
+- Applies to: architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on money, inventory, quotas, ownership transfers, balance updates
+- Required evidence: transactional boundary (DB transaction, row lock, or equivalent) plus a concurrency test or documented invariant proving no double-spend / lost update. N/A when feature has no shared mutable state.
+
+### SEC-SBD-05 — Secrets outside code
+
+- Maps to: OWASP A02 / A05
+- Default severity: `critical` (committed) / `high` (config drift)
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on any commit
+- Required evidence: secrets loaded from environment / vault / managed config; `.env` and equivalents in `.gitignore`; secret-scan pass on diff. Brownfield exception: pre-existing secret must be rotated and tracked, never silently kept.
+
+### SEC-SBD-06 — External URL sanitization
+
+- Maps to: OWASP A03 / A10
+- Default severity: `medium` (raises to `high` when URL is followed server-side)
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts or follows external URLs
+- Required evidence: scheme allowlist, host validation, SSRF protection (private-range block) when followed server-side, escaping when rendered. N/A when no external URL is accepted.
+
+### SEC-SBD-07 — Storage default-deny / RLS boundary
+
+- Maps to: OWASP A01 / A05
+- Default severity: `critical`
+- Owner agent: `@architect` (designs), `@dev` (implements), `@qa` (verifies)
+- Applies to: architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on every multi-tenant or per-user store
+- Required evidence: storage layer denies by default (RLS policies enabled, bucket private, queue ACL closed) plus a negative test from an unauthorized identity. N/A when storage is single-tenant and intentionally public.
+
+### SEC-SBD-08 — Auth enumeration / rate limiting
+
+- Maps to: OWASP A07
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on login, password reset, signup, OTP and any auth-adjacent endpoint
+- Required evidence: per-endpoint rate limit (per IP and per identifier), uniform error response for "user not found" vs "wrong password", lockout or backoff after N failures, and a negative test asserting enumeration is not possible. N/A when feature has no auth surface.
+
+## Out of scope (v1)
+
+The following are explicitly **not** part of this baseline and require a future
+PRD before adoption: deceptive endpoints (honeypots), jump-scare responses,
+adversarial CAPTCHAs, and any technique whose primary purpose is to deceive
+attackers. The baseline is preventive, not deceptive.
+
+## Maintenance
+
+- Control IDs are stable. Adding a control means appending `SEC-SBD-09`, never
+  renumbering or repurposing an existing ID.
+- Severity defaults can be raised per-feature in `spec-{slug}.md` with rationale; they cannot be silently lowered.
+- Changes to this rule require an explicit decision recorded in the relevant
+  feature spec and a `last_amended`-style note in the constitution if they
+  alter Article VII semantics.

package/template/.aioson/rules/spec-level-ownership.md

@@ -0,0 +1,61 @@
+---
+name: spec-level-ownership
+description: spec.md é de projeto, spec-{slug}.md é de feature — os dois níveis nunca se misturam
+priority: 9
+version: 1.0.0
+agents: [dev, qa, pm, sheldon]
+---
+
+# Spec Ownership: Project vs Feature Level
+
+Two distinct levels — never mix them.
+
+| File | Level | Owner | Content |
+|---|---|---|---|
+| `spec.md` | **Project** | `@dev` (full project) | Stack, global patterns, infrastructure — decisions affecting the whole project |
+| `spec-{slug}.md` | **Feature** | `@dev` (specific feature) | Decisions, entities, dependencies, ACs for ONE feature |
+
+## Absolute rules
+
+1. `spec.md` never receives feature-specific content → create `spec-{slug}.md` for that.
+2. `spec-{slug}.md` never receives project decisions → stack decisions go in `spec.md` or `architecture.md`.
+3. `spec-{slug}.md` is created by `@dev` at feature implementation start. One file per slug. Slug must match `prd-{slug}.md` and `implementation-plan-{slug}.md`.
+4. No `spec-{slug}.md` without a corresponding `prd-{slug}.md`.
+
+## Mandatory structure: spec-{slug}.md
+
+```markdown
+---
+feature: {slug}
+status: in_progress | done
+phase_gates:
+  requirements: approved | pending | skipped
+  design: approved | pending | skipped
+  plan: approved | pending | skipped
+---
+
+# Spec — {feature name}
+
+## Implemented entities
+## Technical decisions
+## Dependencies
+## QA approval
+(filled by @qa on feature close)
+```
+
+## Mandatory structure: spec.md (project level)
+
+```markdown
+# Spec — {project name}
+
+## Stack and infrastructure
+## Global code patterns
+## External integrations
+## Cross-feature architecture decisions
+```
+
+## On violation detected
+
+1. Do not write to the wrong file.
+2. Identify the correct level.
+3. Write to the correct file (create if needed following mandatory structure above).