@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/rules/canonical-path-contract.md

@@ -1,47 +1,47 @@
----
-name: canonical-path-contract
-description: Distinção obrigatória entre plans/ root, .aioson/plans/{slug}/, docs/pt/ e implementation-plan. Todo agente que escreve artefatos deve consultar este contrato antes de criar arquivos.
-priority: 10
-version: 1.0.0
-agents: []
----
-
-# Canonical Path Contract
-
-Every agent that creates or writes files MUST resolve the target path using this contract before writing.
-
-## The three confusable directories
-
-| Directory | Purpose | Write rule |
-|---|---|---|
-| `plans/` (root) | Pre-production research and source material only | READ-ONLY for agents. Exception: `plans/source-manifest.md` may be updated when consuming a source plan. |
-| `.aioson/plans/{slug}/` | Active phased plan produced by `@sheldon` | Written by `@sheldon`. Consumed by `@dev` and `@qa` during execution. |
-| `docs/pt/` | Public system documentation for implemented behavior | Written only after behavior is implemented. Never used as operational planning space or scratchpad. |
-
-## Operational artifact destinations
-
-| Artifact | Correct destination | Owner |
-|---|---|---|
-| Operational feature plan (phased) | `.aioson/plans/{slug}/manifest.md` + phase files | `@sheldon` |
-| MEDIUM execution plan | `.aioson/context/implementation-plan-{slug}.md` | `@pm` |
-| PRD | `.aioson/context/prd-{slug}.md` | `@product` |
-| Requirements | `.aioson/context/requirements-{slug}.md` | `@analyst` |
-| Architecture | `.aioson/context/architecture.md` | `@architect` |
-| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
-| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
-
-## Violation behaviors
-
-- If an agent is about to write a plan to `docs/pt/`: stop, use `.aioson/plans/{slug}/` instead.
-- If an agent is about to write an operational artifact to `plans/` root: stop, use the correct `.aioson/context/` or `.aioson/plans/{slug}/` path.
-- If any agent creates a file outside its write scope: stop, identify the correct path, and confirm with the user before writing.
-- Before creating any file, verify the path against `.aioson/context/project-map.md`.
-
-## When the user refers to a directory ambiguously
-
-| User says | Agent resolves to |
-|---|---|
-| "plans" or "plans folder" | Ask: root `plans/` (pre-production) or `.aioson/plans/{slug}/` (feature plan)? |
-| "docs" or "documentation" | Ask: `docs/` root (project docs) or `docs/pt/` (PT system docs) or `.aioson/docs/` (agent on-demand docs)? |
-| "context" | `.aioson/context/` (framework artifacts) |
-| "rules" | `.aioson/rules/` (agent rules) |
+---
+name: canonical-path-contract
+description: Distinção obrigatória entre plans/ root, .aioson/plans/{slug}/, docs/pt/ e implementation-plan. Todo agente que escreve artefatos deve consultar este contrato antes de criar arquivos.
+priority: 10
+version: 1.0.0
+agents: []
+---
+
+# Canonical Path Contract
+
+Every agent that creates or writes files MUST resolve the target path using this contract before writing.
+
+## The three confusable directories
+
+| Directory | Purpose | Write rule |
+|---|---|---|
+| `plans/` (root) | Pre-production research and source material only | READ-ONLY for agents. Exception: `plans/source-manifest.md` may be updated when consuming a source plan. |
+| `.aioson/plans/{slug}/` | Active phased plan produced by `@sheldon` | Written by `@sheldon`. Consumed by `@dev` and `@qa` during execution. |
+| `docs/pt/` | Public system documentation for implemented behavior | Written only after behavior is implemented. Never used as operational planning space or scratchpad. |
+
+## Operational artifact destinations
+
+| Artifact | Correct destination | Owner |
+|---|---|---|
+| Operational feature plan (phased) | `.aioson/plans/{slug}/manifest.md` + phase files | `@sheldon` |
+| MEDIUM execution plan | `.aioson/context/implementation-plan-{slug}.md` | `@pm` |
+| PRD | `.aioson/context/prd-{slug}.md` | `@product` |
+| Requirements | `.aioson/context/requirements-{slug}.md` | `@analyst` |
+| Architecture | `.aioson/context/architecture.md` | `@architect` |
+| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
+| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
+
+## Violation behaviors
+
+- If an agent is about to write a plan to `docs/pt/`: stop, use `.aioson/plans/{slug}/` instead.
+- If an agent is about to write an operational artifact to `plans/` root: stop, use the correct `.aioson/context/` or `.aioson/plans/{slug}/` path.
+- If any agent creates a file outside its write scope: stop, identify the correct path, and confirm with the user before writing.
+- Before creating any file, verify the path against `.aioson/context/project-map.md`.
+
+## When the user refers to a directory ambiguously
+
+| User says | Agent resolves to |
+|---|---|
+| "plans" or "plans folder" | Ask: root `plans/` (pre-production) or `.aioson/plans/{slug}/` (feature plan)? |
+| "docs" or "documentation" | Ask: `docs/` root (project docs) or `docs/pt/` (PT system docs) or `.aioson/docs/` (agent on-demand docs)? |
+| "context" | `.aioson/context/` (framework artifacts) |
+| "rules" | `.aioson/rules/` (agent rules) |

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

@@ -1,74 +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
-
-## 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
+---
+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

@@ -1,44 +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`.
+---
+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

@@ -1,44 +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
+---
+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

@@ -1,49 +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.).
+---
+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.).