@orderful/droid 0.35.4 → 0.37.0

package/src/tools/codex/skills/codex/SKILL.md

@@ -14,6 +14,7 @@ allowed-tools:
     Bash(ls:*),
     Bash(mkdir:*),
     Bash(droid:*),
+    Bash(cat:*),
   ]
 ---
 
@@ -23,399 +24,189 @@ allowed-tools:
 
 Shared organizational knowledge for humans and droids alike. Product requirements documents, tech designs, patterns, and explored topics - structured for AI-assisted development.
 
-## Prerequisites
-
-Before using codex, verify:
-
-1. **Repo cloned:** Check if `codex_repo` path exists
-2. **gh CLI:** Required for PR workflows (CONTEXT.md auto-generation)
-
-```bash
-# Check repo exists
-ls -la {codex_repo}
-
-# Check gh CLI
-gh --version
-```
-
-If prerequisites fail, guide user to fix:
-
-- Repo missing: `git clone git@github.com:orderful/orderful-codex.git {path}`
-- gh missing: `brew install gh && gh auth login`
-
-## Git Hygiene (CRITICAL)
-
-**Users should never see git complexity.** Use the deterministic scripts below - they handle all git operations silently and recover gracefully. Non-engineers use this tool - if they hit a git error, they're stuck.
-
-### Scripts
-
-The codex skill includes three git scripts. **Always use these instead of raw git commands.**
-
-| Script             | Purpose                         | When to use             |
-| ------------------ | ------------------------------- | ----------------------- |
-| `git-preamble`     | Ensure clean main + pull latest | Before ANY operation    |
-| `git-start-write`  | Preamble + create branch        | Before write operations |
-| `git-finish-write` | Commit + PR + return to main    | After write operations  |
-
-### Read Operations (search, load, list)
+## Self-Describing Architecture
 
-```bash
-droid config --get tools.codex | droid exec codex git-preamble --config -
-# Then proceed with the read
-```
+**The codex repo defines its own structure and workflows.** The skill reads these on each operation instead of having hardcoded assumptions.
 
-### Write Operations (new, decision, snapshot, artifact)
+**On every codex operation:**
 
-```bash
-# 1. Start write (runs preamble + creates branch)
-droid config --get tools.codex | droid exec codex git-start-write --config - --branch codex/{action}-{name}
+1. **Read structure:** `{codex_repo}/.codex/manifest.yaml` defines categories, scaffolding rules, frontmatter schema
+2. **Read workflow:** `{codex_repo}/.codex/workflows/{operation}.md` provides step-by-step instructions
+3. **Execute:** Follow the workflow instructions using your tools
 
-# 2. Make your changes (write files)
+**Workflow mapping:**
 
-# 3. Finish write (commit + PR + return to main)
-droid config --get tools.codex | droid exec codex git-finish-write --config - \
-  --message "{commit message}" \
-  --pr-title "{PR title}" \
-  --pr-body "{PR description}"
-```
+| Operation | Workflow File |
+|-----------|---------------|
+| Load/search/list operations | .codex/workflows/loading.md |
+| Create new entries | .codex/workflows/creating.md |
+| Add to existing entries | .codex/workflows/adding.md |
+| Review documents | .codex/workflows/reviewing.md |
 
-The scripts return JSON with success/failure status. Check the result before proceeding.
-
-### Error Handling
-
-The scripts handle errors internally:
-
-- Silent recovery for transient issues
-- Clear error messages in JSON output
-- Automatic return to main even on partial failure
-
-If a script fails, check the JSON `error` field and report a user-friendly message:
+**Example - creating a project:**
 
-- "I hit a sync issue with the codex. Let me try again..."
-- Only escalate as last resort: "The codex repo needs manual attention."
-
-## Security
+    # 1. Read workflow
+    cat {codex_repo}/.codex/workflows/creating.md
 
-### Input Validation
+    # 2. Read manifest for scaffold rules
+    cat {codex_repo}/.codex/manifest.yaml
+    # Extract: categories.projects.minimal_scaffold
 
-**Always validate user-provided names before using in paths:**
+    # 3. Follow procedure in creating.md
 
-```bash
-# REJECT names containing path traversal attempts
-if [[ "{name}" == *".."* ]] || [[ "{name}" == *"/"* ]]; then
-  echo "Invalid name: must not contain '..' or '/'"
-  exit 1
-fi
+See `references/reading-workflows.md` for detailed guidance on interpreting workflows.
 
-# REJECT names with shell metacharacters
-if [[ "{name}" =~ [\$\`\|\;\&\>\<] ]]; then
-  echo "Invalid name: contains unsafe characters"
-  exit 1
-fi
-```
-
-### Safe Git Commits
+## Prerequisites
 
-**Use heredoc for commit messages to prevent injection:**
+Before using codex, verify:
 
-```bash
-# GOOD - safe from injection
-git commit -F - <<EOF
-decision({active}): {summary}
-EOF
+1. **Repo cloned:** Check if `codex_repo` path exists
+2. **gh CLI:** Required for PR workflows
 
-# BAD - vulnerable to injection
-git commit -m "decision({active}): {summary}"
-```
+    # Check repo exists
+    ls -la {codex_repo}
 
-### Access Control
+    # Check gh CLI
+    gh --version
 
-**Check repo access before attempting write operations:**
+If prerequisites fail, guide user to fix:
 
-```bash
-# Verify push access before making changes
-if ! git -C {codex_repo} push --dry-run 2>/dev/null; then
-  echo "Error: No push access to codex repo. Check your permissions."
-  exit 1
-fi
-```
+- Repo missing: `git clone git@github.com:orderful/orderful-codex.git {path}`
+- gh missing: `brew install gh && gh auth login`
 
 ## Configuration
 
 **ALWAYS run `droid config --get tools.codex` first and parse the JSON output.**
 
-| Setting          | Default                           | Description                   |
-| ---------------- | --------------------------------- | ----------------------------- |
-| `codex_repo`     | `~/src/github.com/orderful-codex` | Path to local codex repo      |
-| `freshness_days` | `30`                              | Days before staleness warning |
-
-## Categories
-
-The codex has five categories:
-
-| Category    | Path                      | Purpose                                               |
-| ----------- | ------------------------- | ----------------------------------------------------- |
-| `projects`  | `{codex_repo}/projects/`  | Feature/project context (PRD, tech design, decisions) |
-| `domains`   | `{codex_repo}/domains/`   | Business domain knowledge - the "what" and "why"      |
-| `proposals` | `{codex_repo}/proposals/` | Ideas and future direction - not yet committed        |
-| `patterns`  | `{codex_repo}/patterns/`  | Cross-cutting technical patterns                      |
-| `topics`    | `{codex_repo}/topics/`    | Explored codebase areas with freshness tracking       |
+| Setting | Default | Description |
+|---------|---------|-------------|
+| codex_repo | ~/src/github.com/orderful-codex | Path to local codex repo |
+| freshness_days | 30 | Days before staleness warning |
 
 ## Commands
 
-| Command                                | Action                                          |
-| -------------------------------------- | ----------------------------------------------- |
-| `/codex`                               | Show categories overview                        |
-| `/codex projects`                      | List all projects                               |
-| `/codex domains`                       | List all domains                                |
-| `/codex proposals`                     | List all proposals                              |
-| `/codex patterns`                      | List all patterns                               |
-| `/codex topics`                              | List all topics                                         |
-| `/codex search {query}`                      | Search and load entry (searches all categories)         |
-| `/codex search {query} -- {instruction}`     | Search, load, then execute follow-up instruction        |
-| `/codex {category} search {query}`           | Search within a specific category only                  |
-| `/codex review {type} --pr {number}`         | Conversational review of a document PR                  |
-| `/codex new {category} {name}`               | Scaffold new entry (project/domain/proposal/pattern/topic) |
-| `/codex decision {text}`                     | Append to active project's DECISIONS.md                 |
-| `/codex snapshot {type} {file} {name}` | Import PDF/markdown to codex (uses agent)       |
-| `/codex artifact {file} {project}`     | Add supporting artifact to project (uses agent) |
-
-## Loading an Entry
-
-**Trigger:** `/codex search {query}` or user asks to load/check codex for something
-
-**Category-scoped search:** Narrow search to a specific category:
-```bash
-/codex topics search auth           # Search within topics only
-/codex patterns search webhook      # Search within patterns only
-/codex projects search transaction  # Search within projects only
-```
-
-**Follow-up instructions:** Use `--` to add an instruction to execute after loading:
-```bash
-/codex search transaction-templates -- summarize the PRD
-/codex topics search auth -- is this still accurate?
-```
-Parse args by splitting on ` -- `. First part = search terms, second part = instruction to execute after loading.
-
-**Procedure:**
-
-1. **Run preamble first:**
-   ```bash
-   droid config --get tools.codex | droid exec codex git-preamble --config -
-   ```
-2. **Read `{codex_repo}/index.yaml`** - this contains all entry names and aliases for fast lookup
-3. Match `{name}` against index keys and aliases (case-insensitive, partial match)
-4. If multiple matches → show list, let user pick
-5. If single match → load directly from the matched path
-6. **For projects → use progressive disclosure:**
-   - If CONTEXT.md exists → load it automatically (layer 1)
-   - Offer deeper files only if user needs more detail
-   - If no CONTEXT.md → synthesise one first (see below)
-7. Check freshness (see below)
-8. Output loaded content with "need more detail?" options
-
-**Why index?** Avoids expensive file-by-file searching. One read to find any entry by name or alias.
-
-**Progressive disclosure:** CONTEXT.md is the first layer - a synthesised summary (~2KB) that handles most queries. Only load full PRD/TECH-DESIGN/DECISIONS files when deeper detail is explicitly needed. This avoids loading 30KB+ of docs for simple context questions.
-
-**If no CONTEXT.md exists for a project:**
-
-- Synthesise one from PRD.md + TECH-DESIGN.md + DECISIONS.md
-- Create branch, commit CONTEXT.md, open PR
-- Output the new CONTEXT.md with "need more detail?" options
-- **OPTIONAL:** You may use a background agent (Task tool with `run_in_background: true`) to avoid blocking the user, but synchronous generation is fine too
-
-Full procedure: `references/loading.md`
-
-## Freshness Checking
-
-All codex files have frontmatter:
-
-```yaml
----
-title: Feature Name
-type: prd | tech-design | context | decisions | pattern | topic | domain | proposal
-status: draft | active | complete | archived
-created: 2026-01-07
-updated: 2026-01-07
-confidence: high | medium | low
-source: confluence | exploration | implementation
-codebase_paths:
-  - apps/platform-api/src/...
----
-```
-
-**Status values (unified across all categories):**
-
-- `draft` - Initial capture, not ready for consumption
-- `active` - Current, being used for implementation
-- `complete` - Project shipped, kept for reference
-- `archived` - No longer relevant, kept for history
-
-**When loading any file:**
-
-1. Parse frontmatter for `updated` date
-2. Calculate days since update
-3. If > `freshness_days` (default 30):
-   - Warn: "This doc was last updated {date} ({n} days ago). Want me to verify it's still accurate?"
-4. If `codebase_paths` present:
-   - Check if those paths have commits since `updated` date
-   - If yes: "Files in {paths} have changed since this doc was updated. Want me to review?"
-5. If `confidence: low`:
-   - Note: "This was a quick exploration and may be incomplete"
-
-## Active Project Tracking
-
-Scoped operations (`decision`, `snapshot`) require an active project:
-
-- When user loads a project via `/codex search {project-name}`, set it as active
-- Store active project name in session context
-- If scoped operation called with no active project → show project list, let user pick
-
-## Adding Decisions
-
-**Trigger:** `/codex decision {text}` or user wants to capture a decision
-
-**Procedure:**
-
-1. Verify active project exists (if not, prompt to select)
-2. **Run `git-start-write`** with branch `codex/decision-{short-summary}`
-3. Read and append to `{codex_repo}/projects/{active}/DECISIONS.md`
-4. Update `updated` date in frontmatter
-5. **Run `git-finish-write`** with appropriate commit message and PR title
+All codex operations follow workflows defined in the codex repo's `.codex/workflows/` folder.
 
-Full procedure: `references/decisions.md`
+Commands listed below are **convenience aliases** to common workflow operations. Natural language like "add this decision to the codex" works equally well - the AI will map your intent to the appropriate workflow.
 
-## Adding Topics
+### Loading & Searching
 
-**Trigger:** `/codex new topic {name}` or user wants to save exploration
+- `/codex` → List categories (workflows/loading.md)
+- `/codex {category}` → List entries in category (workflows/loading.md)
+- `/codex search {query}` → Search and load entry (workflows/loading.md)
+- `/codex search {query} -- {instruction}` → Search, load, then execute follow-up (workflows/loading.md)
+- `/codex {category} search {query}` → Category-scoped search (workflows/loading.md)
 
-**Procedure:**
+### Creating New Entries
 
-1. **Run `git-start-write`** with branch `codex/topic-{name}`
-2. Create `{codex_repo}/topics/{name}.md` from template
-3. Fill in frontmatter (explored, confidence, codebase_paths)
-4. Fill in content from current exploration/conversation
-5. **Run `git-finish-write`** with appropriate commit message and PR title
+- `/codex new {category} {name}` → Scaffold new entry (workflows/creating.md)
+  - Categories are defined in manifest: projects, domains, proposals, patterns, topics
+  - Run: `cat {codex_repo}/.codex/manifest.yaml` to see full structure
 
-Full procedure: `references/topics.md`
+### Adding to Existing Entries
 
-## Importing Documents
+These are convenience aliases - workflows/adding.md defines the behaviour:
 
-**Trigger:** `/codex snapshot {type} {file} {name}` or user wants to add a file to the codex
+- `/codex decision {text}` - Append decision to active project
+- `/codex action {text}` - Add action item to active project
+- `/codex artifact {file} {project}` - Add supporting artifact
+- `/codex snapshot {type} {file} {name}` - Import document
 
-**IMPORTANT:** Always use the `codex-document-processor` agent to process documents. This keeps the main conversation context lean by offloading heavy document processing.
+### Reviewing Documents
 
-**Procedure:**
+- `/codex review {type} --pr {number}` → Conversational review
+  - Generic flow: workflows/reviewing.md (codex repo)
+  - Type-specific facilitation: `references/review/{type}.md` (droid)
 
-1. Determine the document type (required): `prd`, `tech-design`, `topic`, or `pattern`
-2. **Run `git-start-write`** with branch `codex/snapshot-{name}`
-3. Spawn the `codex-document-processor` agent with:
-   - File path to the source document
-   - Document type
-   - Project/entry name
-   - Codex repo path from config
-4. Agent writes the processed document to codex repo
-5. **Run `git-finish-write`** with appropriate commit message and PR title
-6. Share PR link with user
+**Architecture:** Codex defines the generic review flow (load PR, navigate sections, provide feedback). Droid defines type-specific facilitation guidance (file patterns, section parsing, consistency checks). This separation ensures the core flow stays in codex while specialized AI instructions stay in droid.
 
-**Example invocations:**
+**Available types:** `tech-design`, `prd`
 
-```bash
-# Explicit snapshot command
-/codex snapshot prd ~/Downloads/transaction-templates-prd.pdf transaction-templates
+**Important:** The workflows define behaviour, not the command names. When the codex structure evolves (new file types, new operations), only the codex repo's workflows need updating - the droid skill stays stable.
 
-# Natural language (still uses the agent)
-"Add this PRD to the transaction-templates project" + attach file
-"Import this tech design to generic-scenario-testing"
-```
-
-The agent handles: PDF reading, content extraction, frontmatter generation, file writing.
-The main conversation handles: git branch, commit, PR creation, user interaction.
-
-## Adding Artifacts
+## Git Hygiene (CRITICAL)
 
-**Trigger:** `/codex artifact {file} {project}` or user wants to add supporting material to a project
+**Users should never see git complexity.** Use the deterministic scripts below - they handle all git operations silently and recover gracefully. Non-engineers use this tool - if they hit a git error, they're stuck.
 
-Artifacts are supplementary documents that support a project but aren't core document types (PRD, TECH-DESIGN, DECISIONS). Examples:
+### Scripts
 
-- Customer interviews / transcripts
-- Research notes
-- Meeting summaries
-- Spike findings
-- Competitor analysis
+The codex skill includes three git scripts. **Always use these instead of raw git commands.**
 
-**Procedure:**
+| Script | Purpose | When to use |
+|--------|---------|-------------|
+| git-preamble | Ensure clean main + pull latest | Before ANY operation |
+| git-start-write | Preamble + create branch | Before write operations |
+| git-finish-write | Commit + PR + return to main | After write operations |
 
-1. **Run `git-start-write`** with branch `codex/artifact-{project}-{filename}`
-2. Use the `codex-document-processor` agent with type `artifact`
-3. Agent writes to `{codex_repo}/projects/{project}/artifacts/{filename}.md`
-4. **Run `git-finish-write`** with appropriate commit message and PR title
+### Read Operations
 
-**Example invocations:**
+    droid config --get tools.codex | droid exec codex git-preamble --config -
+    # Then proceed with the read
 
-```bash
-/codex artifact ~/Downloads/customer-interview-acme.pdf transaction-templates
-/codex artifact ~/notes/spike-handlebars-perf.md partnership-automation
-```
+### Write Operations
 
-Artifacts get lighter frontmatter with `type: artifact` and source like `interview`, `transcript`, `notes`, `meeting`, `research`, `spike`, or `analysis`.
+    # 1. Start write (runs preamble + creates branch)
+    droid config --get tools.codex | droid exec codex git-start-write --config - --branch codex/{action}-{name}
 
-## Reviewing Documents
+    # 2. Make your changes (write files)
 
-**Trigger:** `/codex review {type} --pr {number}`
+    # 3. Finish write (commit + PR + return to main)
+    droid config --get tools.codex | droid exec codex git-finish-write --config - \
+      --message "{commit message}" \
+      --pr-title "{PR title}" \
+      --pr-body "{PR description}"
 
-**Procedure:**
+The scripts return JSON with success/failure status. Check the result before proceeding.
 
-1. **Run preamble:** `droid config --get tools.codex | droid exec codex git-preamble --config -`
-2. **Fetch PR info:** `gh pr view {number} --json files,title`
-3. **Filter & Load:** Identify the primary document (e.g., `TECH-DESIGN.md`) and context (e.g., `thought-doc.md`) based on the `{type}` definition.
-4. **Interactive Review:** Guide the user through the document sections.
+### Error Handling
 
-Full procedure: `references/review/workflow.md`
-Type definitions: `references/review/{type}.md`
+The scripts handle errors internally:
 
-## Creating New Entries
+- Silent recovery for transient issues
+- Clear error messages in JSON output
+- Automatic return to main even on partial failure
 
-**Trigger:** `/codex new {category} {name}`
+If a script fails, check the JSON `error` field and report a user-friendly message:
 
-**Categories:** `project` | `domain` | `proposal` | `pattern` | `topic`
+- "I hit a sync issue with the codex. Let me try again..."
+- Only escalate as last resort: "The codex repo needs manual attention."
 
-**Procedure** (same for all categories):
+## Security
 
-1. **Run `git-start-write`** with branch `codex/{category}-{name}`
-2. Create entry from template:
-   - `project` → folder with PRD.md, TECH-DESIGN.md, DECISIONS.md
-   - Others → single file at `{codex_repo}/{category}s/{name}.md`
-3. Fill in frontmatter with today's date
-4. **Run `git-finish-write`** with appropriate commit message and PR title
+### Input Validation
 
-Full procedure: `references/creating.md`
+**Always validate user-provided names before using in paths:**
 
-## Integration with /project
+    # REJECT names containing path traversal attempts
+    if [[ "{name}" == *".."* ]] || [[ "{name}" == *"/"* ]]; then
+      echo "Invalid name: must not contain '..' or '/'"
+      exit 1
+    fi
 
-The codex holds **shared** organizational knowledge. The `/project` skill holds **personal** working memory.
+    # REJECT names with shell metacharacters
+    if [[ "{name}" =~ [\$\`\|\;\&\>\<] ]]; then
+      echo "Invalid name: contains unsafe characters"
+      exit 1
+    fi
 
-```
-/codex search transaction-templates       → load shared context
-/project create --from codex:{name}       → seed personal PROJECT.md
-/codex publish                            → promote learnings back (future)
-```
+### Safe Git Commits
 
-When user runs `/project create --from codex:{name}`:
+**Use heredoc for commit messages to prevent injection:**
 
-1. Load the codex entry
-2. Extract key context for personal PROJECT.md
-3. Create project in user's projects_dir
+    # GOOD - safe from injection
+    git commit -F - <<EOF
+    decision({active}): {summary}
+    EOF
 
-## Git Workflow
+    # BAD - vulnerable to injection
+    git commit -m "decision({active}): {summary}"
 
-**See "Git Hygiene (CRITICAL)" section above.** All codex changes go through PRs (main branch is protected).
+### Access Control
 
-**Key points:**
+**Check repo access before attempting write operations:**
 
-- Always run the preamble before any operation (ensures clean main + latest)
-- Write operations: branch → commit → PR → **return to main**
-- Safe changes (new files, decision appends) auto-merge via GitHub Action
-- Never leave the repo on a feature branch
+    # Verify push access before making changes
+    if ! git -C {codex_repo} push --dry-run 2>/dev/null; then
+      echo "Error: No push access to codex repo. Check your permissions."
+      exit 1
+    fi

package/src/tools/codex/skills/codex/references/reading-workflows.md

@@ -0,0 +1,56 @@
+# Reading Codex Workflows
+
+Codex workflows are AI-readable markdown files that describe how to perform operations.
+
+## Workflow Structure
+
+Each workflow file follows this pattern:
+
+### Trigger
+When to use this workflow (command pattern or user intent)
+
+### Procedure
+Step-by-step instructions with bash commands and file operations
+
+### Output
+What to show the user
+
+## Reading a Workflow
+
+1. **Read entire workflow file:**
+
+       cat {codex_repo}/.codex/workflows/{operation}.md
+
+2. **Parse the Procedure section** - Follow steps sequentially
+
+3. **Reference manifest when needed:**
+   - Scaffold rules: categories.{type}.minimal_scaffold
+   - Frontmatter schema: file_types.{type}
+   - Templates location: templates_dir
+
+4. **Execute using your tools** (Read, Write, Bash, etc.)
+
+## Example: Creating a Project
+
+    # 1. Read workflow
+    cat {codex_repo}/.codex/workflows/creating.md
+
+    # 2. Read manifest for scaffold
+    cat {codex_repo}/.codex/manifest.yaml
+    # Extract: categories.projects.minimal_scaffold → ["CONTEXT.md", "DECISIONS.md"]
+
+    # 3. Follow workflow procedure
+    # - Start git write
+    # - mkdir projects/{name}
+    # - Copy templates
+    # - Update frontmatter
+    # - Finish git write
+
+## Workflow Files
+
+| File | Purpose |
+|------|---------|
+| loading.md | Search, match, progressive disclosure, freshness checking |
+| creating.md | Scaffold new entries (projects, domains, patterns, topics, proposals) |
+| adding.md | Write to existing entries (decisions, actions, artifacts, snapshots) |
+| reviewing.md | Conversational PR review with section navigation |

package/src/tools/codex/skills/codex/references/review/prd.md

@@ -0,0 +1,49 @@
+# PRD Document Type
+
+Configuration for reviewing Product Requirements Documents via `/codex review prd`.
+
+## File Patterns
+
+| Role | Pattern | Description |
+| --- | --- | --- |
+| **Primary** | `**/PRD.md` | The main document being reviewed. Sections are parsed from here. |
+| **Context** | `**/artifacts/*.md` | Supporting materials. Check frontmatter for type/source to identify purpose. |
+
+**Context file types** (identified by frontmatter):
+- `type: artifact` with `source: interview` → Customer interviews
+- `type: artifact` with `source: research` → Research notes
+- `type: artifact` with `source: analysis` → Competitive analysis
+- `type: artifact` with `source: meeting` → Meeting notes
+
+*Note: In the MVP, we assume a single PRD.md per PR.*
+
+## Section Parsing
+
+**Parse sections flexibly based on the document's actual structure.** Different PMs have different organisational preferences.
+
+**Suggested approach:**
+- Try H2 headers (`## `) as top-level sections first
+- If the document uses H3 (`###`) as primary sections, adapt to that
+- Look at the document hierarchy and follow what the author used
+
+**The tool dynamically discovers ALL sections present in the document.** It does not filter for specific section names - let the PM's structure guide the review navigation.
+
+**Common sections** (examples, not exhaustive):
+- Overview
+- Problem Statement
+- User Stories
+- Requirements
+- Success Metrics
+- Timeline
+- Out of Scope
+- Open Questions
+- Competitive Analysis
+
+Authors may include additional sections (e.g., "Security Requirements", "Compliance", "Business Impact") and the tool will present them for navigation.
+
+## Consistency Checks (Deferred)
+
+*Future feature: Rules to automatically check consistency.*
+- "Success Metrics" section must have measurable criteria
+- "Requirements" should distinguish functional vs non-functional
+- "Out of Scope" should reference items mentioned elsewhere