docs(meta): repoint decisions/ paths to governance/ tree (pql migration)
Phase 1 follow-up: update the active instruction layer (CLAUDE.md, project
structure rule, DECISIONS.md redirect, agent personalities, skill docs) to
reference governance/{decisions,questions,rejected}/<domain>.md instead of the
retired flat decisions/*.md layout.
Path references only — command-surface references (tooling/db/decision*,
decisions-sync, Makefile targets, clerk) are repointed to the pql CLI in the
Phase 4 consumer cutover. Historical archives (docs/sprints, docs/discussions,
docs/workshops) keep their point-in-time decisions/ paths; the separate
whatsinagame/ template distribution is untouched. Agent-memory is gitignored
and out of scope.
The agent/skill repath was applied by tooling/pql-migrate/repath_references.py
(ordered, meaning-preserving replacements; bare-dir rule uses a negative
lookbehind so it can't corrupt a freshly-created governance/decisions/ path),
committed for provenance. CLAUDE.md, project-structure.md, and DECISIONS.md
were hand-edited (structural tree/table changes).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.8
@@ -134,7 +134,7 @@ To add a new agent:
|
||||
## Project documents
|
||||
|
||||
All agents read their briefing at `docs/briefings/{name}.md` for current context. Key project documents:
|
||||
- `decisions/` - Domain-split decision files (see decisions/README.md for index)
|
||||
- `governance/` - Domain-split decision files (see governance/README.md for index)
|
||||
- `DISCUSSION.md` - Active discussion round (archives in `docs/discussions/`)
|
||||
- `TEAM.md` - Team roster and role descriptions
|
||||
- `CLAUDE.md` - Project-wide conventions
|
||||
|
||||
@@ -67,4 +67,4 @@ When working on visual assets:
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/araminta.md` before starting work - it lists all visual design decisions and surfaces. Read the relevant decisions/ domain files for the full specifications.
|
||||
Read your briefing at `docs/briefings/araminta.md` before starting work - it lists all visual design decisions and surfaces. Read the relevant governance/ domain files for the full specifications.
|
||||
|
||||
@@ -38,4 +38,4 @@ Named for the Burnelli-Sheldon dynasty — old money that understood how wealth
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/burnelli-sheldon.md` before starting work (if it exists). Read the relevant `decisions/*.md` domain files referenced in your ticket. Key references: D-117 (tycoon bookmark), D-118 (small business owner), D-131 (economic verb vocabulary), D-132 (dual-scale consequence model).
|
||||
Read your briefing at `docs/briefings/burnelli-sheldon.md` before starting work (if it exists). Read the relevant `governance/**/*.md` domain files referenced in your ticket. Key references: D-117 (tycoon bookmark), D-118 (small business owner), D-131 (economic verb vocabulary), D-132 (dual-scale consequence model).
|
||||
|
||||
@@ -39,4 +39,4 @@ When spawned manually for an audit:
|
||||
|
||||
## Project context
|
||||
|
||||
Read `decisions/README.md` for the domain index. The `decisions` table in the ticketing DB is synced from these files via `tooling/db/decisions-sync`.
|
||||
Read `governance/README.md` for the domain index. The `decisions` table in the ticketing DB is synced from these files via `tooling/db/decisions-sync`.
|
||||
|
||||
@@ -38,4 +38,4 @@ Originally a Stellaris mechanics fan, you pivoted to general systems design when
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/gestalt.md` before starting work. Read the relevant decisions/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions.
|
||||
Read your briefing at `docs/briefings/gestalt.md` before starting work. Read the relevant governance/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions.
|
||||
|
||||
@@ -34,4 +34,4 @@ Named after Gore Burnelli - the dynasty patriarch who sees further than anyone,
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/gore.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
Read your briefing at `docs/briefings/gore.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
|
||||
@@ -21,7 +21,7 @@ Named after Hoshe Finn - Paula Myo's detective partner who does the legwork, che
|
||||
- **Create test plans** for new features before implementation begins
|
||||
- **Write test reports** documenting what was tested, what passed, what failed
|
||||
- **Regression testing** - ensure new changes don't break existing functionality
|
||||
- **Verify implementations against specifications** - compare code behavior to decisions/ domain file requirements
|
||||
- **Verify implementations against specifications** - compare code behavior to governance/ domain file requirements
|
||||
- **Edge case identification** - think about what breaks when inputs are unexpected
|
||||
- **Performance testing** - identify bottlenecks, especially in perception/LOS/chunk systems
|
||||
- **Playtest reports** - structured feedback on whether the game feels right
|
||||
@@ -68,4 +68,4 @@ For each feature, create a test plan covering:
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/hoshe.md` before starting work - it lists all systems to test with their decision references. Read the decisions/ specifications that define expected behavior. Tests should always reference specific decisions.
|
||||
Read your briefing at `docs/briefings/hoshe.md` before starting work - it lists all systems to test with their decision references. Read the governance/ specifications that define expected behavior. Tests should always reference specific decisions.
|
||||
|
||||
@@ -40,4 +40,4 @@ Core worldbuilding domains:
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/miri.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context on confirmed decisions and ongoing discussions.
|
||||
Read your briefing at `docs/briefings/miri.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context on confirmed decisions and ongoing discussions.
|
||||
|
||||
@@ -36,4 +36,4 @@ Named after Nigel Sheldon - the inventor, the builder, the man who looks at a pr
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/nigel.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
Read your briefing at `docs/briefings/nigel.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
|
||||
@@ -34,4 +34,4 @@ You're named after Ozzie Isaacs - the wanderer, the dreamer, the one who walks t
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/ozzie.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
Read your briefing at `docs/briefings/ozzie.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
|
||||
@@ -35,4 +35,4 @@ Named after Paula Myo - the investigator who never gives up, who follows the thr
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/paula.md` before starting work. Read the relevant decisions/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
Read your briefing at `docs/briefings/paula.md` before starting work. Read the relevant governance/ domain files listed in your briefing and DISCUSSION.md for full context.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: qatux
|
||||
description: Documenter and Librarian for the Settled Reach game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains decisions/ domain files, DISCUSSION.md, and briefings.
|
||||
description: Documenter and Librarian for the Settled Reach game project. Use when discussion decisions need to be recorded, when documents need updating, when the team needs a summary of current state, when open questions need tracking, when searching project history, or when answering "did we already discuss this?". Maintains governance/ domain files, DISCUSSION.md, and briefings.
|
||||
tools: Read, Glob, Grep, Edit, Write, Bash, SendMessage, TaskList, TaskUpdate, TaskGet
|
||||
model: sonnet
|
||||
memory: project
|
||||
@@ -17,7 +17,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
|
||||
## Your role on the team
|
||||
|
||||
### Documentation
|
||||
- Maintain decisions/ domain files with confirmed decisions (D-NNN format)
|
||||
- Maintain governance/ domain files with confirmed decisions (D-NNN format)
|
||||
- Work directly in round documents at `docs/discussions/round-NN-topic.md` (DISCUSSION.md is retired for new content)
|
||||
- Update TEAM.md when roles change
|
||||
- Track open questions (Q-NNN format) and their status
|
||||
@@ -51,7 +51,7 @@ Named after Qatux, the Raiel with perfect memory who helped Paula Myo by recalli
|
||||
|
||||
## Document formats
|
||||
|
||||
### decisions/ domain files
|
||||
### governance/ domain files
|
||||
Each decision follows this format:
|
||||
```
|
||||
### D-NNN: Short title
|
||||
@@ -62,7 +62,7 @@ Each decision follows this format:
|
||||
- **Dissent:** Any disagreement (or "None")
|
||||
```
|
||||
|
||||
Decisions are now split into domain files at `decisions/*.md`. See `decisions/README.md` for the index. DECISIONS.md is now a redirect file pointing to the domain structure.
|
||||
Decisions are now split into domain files at `governance/**/*.md`. See `governance/README.md` for the index. DECISIONS.md is now a redirect file pointing to the domain structure.
|
||||
|
||||
### DISCUSSION.md
|
||||
Each round follows this format:
|
||||
@@ -78,4 +78,4 @@ Summary table, open questions, flags
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/qatux.md` before starting work. The primary documents you maintain are: decisions/ domain files (see decisions/README.md for index), DISCUSSION.md, TEAM.md. Read them to understand current state before making any updates.
|
||||
Read your briefing at `docs/briefings/qatux.md` before starting work. The primary documents you maintain are: governance/ domain files (see governance/README.md for index), DISCUSSION.md, TEAM.md. Read them to understand current state before making any updates.
|
||||
|
||||
@@ -18,8 +18,8 @@ Named after the Sentient Intelligences that manage all Commonwealth infrastructu
|
||||
You are spawned by `/whats-next` step 2, one instance per ticket in a batch. Your job:
|
||||
|
||||
1. **Research context** for your assigned ticket:
|
||||
- Read the ticket's `decision_ref` D/Q-record in `decisions/*.md`
|
||||
- Grep for related Q-records in `decisions/questions-*.md`
|
||||
- Read the ticket's `decision_ref` D/Q-record in `governance/**/*.md`
|
||||
- Grep for related Q-records in `governance/questions/*.md`
|
||||
- Read workshop outcomes if referenced (check `docs/workshops/`)
|
||||
- Check whether referenced code, tables, or files actually exist
|
||||
|
||||
|
||||
@@ -31,4 +31,4 @@ You are task-oriented. When spawned, you expect a specific question or evaluatio
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/troblum.md` before starting work. Read decisions/architecture.md for architectural requirements - these are your evaluation criteria when assessing technology options.
|
||||
Read your briefing at `docs/briefings/troblum.md` before starting work. Read governance/decisions/architecture.md for architectural requirements - these are your evaluation criteria when assessing technology options.
|
||||
|
||||
@@ -28,4 +28,4 @@ You respect the team leader's 30 years of software/systems/cloud architecture ex
|
||||
|
||||
## Project context
|
||||
|
||||
Read your briefing at `docs/briefings/tyre.md` before starting work - it contains the full list of architectural principles and technical requirements derived from decisions. Read the relevant decisions/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions. The team leader (Jeroen) has 30 years software dev / systems & cloud architect experience and Claude Code 20x access.
|
||||
Read your briefing at `docs/briefings/tyre.md` before starting work - it contains the full list of architectural principles and technical requirements derived from decisions. Read the relevant governance/ domain files listed in your briefing for confirmed decisions and DISCUSSION.md for active discussions. The team leader (Jeroen) has 30 years software dev / systems & cloud architect experience and Claude Code 20x access.
|
||||
|
||||
@@ -35,15 +35,11 @@ tooling/
|
||||
agents/ # Agent personality files
|
||||
skills/ # Skill definitions
|
||||
rules/ # Auto-loaded instruction modules
|
||||
decisions/ # Decision domain files (source of truth)
|
||||
README.md # Domain index — use this to find specific D-records
|
||||
architecture.md # Architecture decisions
|
||||
perception.md # Perception and information system decisions
|
||||
content.md # Content and narrative decisions
|
||||
scope.md # Scope and feature decisions
|
||||
process.md # Process and workflow decisions
|
||||
questions.md # Open questions (Q-NNN)
|
||||
rejected.md # Rejected proposals (R-NNN)
|
||||
DECISIONS.md # Redirect to decisions/ directory
|
||||
governance/ # Decision records (pql DQR tree, source of truth)
|
||||
README.md # Domain guide + pql-maintained record index
|
||||
decisions/ # D-NNN confirmed — <domain>.md (architecture, perception, content, scope, economics, process)
|
||||
questions/ # Q-NNN open — <domain>.md
|
||||
rejected/ # R-NNN rejected — <domain>.md
|
||||
DECISIONS.md # Redirect to governance/ tree
|
||||
TEAM.md # Team roster and roles
|
||||
```
|
||||
|
||||
@@ -95,7 +95,7 @@ content commit — e.g. shipping thousands of generated planetary description fi
|
||||
— that review is moot and just burns agents on noise. Add a `Clerk-Skip:` **trailer
|
||||
line** to the commit message and `tooling/clerk-review` auto-approves that commit
|
||||
without spawning an agent. Use it only for content/data dumps, never for commits
|
||||
that touch `decisions/`, code, or ticket-bearing work.
|
||||
that touch `governance/`, code, or ticket-bearing work.
|
||||
|
||||
It must be a trailer (a line starting with `Clerk-Skip:`), not inline prose — that
|
||||
way a commit that merely *mentions* the token in its subject or body isn't skipped.
|
||||
|
||||
@@ -194,7 +194,7 @@ In the reviewer prompt, state the rule non-negotiably:
|
||||
> Those resolve to main, not the branch. The worktree at `<WORKTREE_PATH>`
|
||||
> IS the branch — point all file tools there.
|
||||
|
||||
Also tell agents to read relevant `decisions/*.md` files for context
|
||||
Also tell agents to read relevant `governance/**/*.md` files for context
|
||||
(these can be read from either path — they're usually identical —
|
||||
but for consistency, use the worktree path).
|
||||
|
||||
@@ -378,7 +378,7 @@ to merge from main (section 7)."
|
||||
rather than a single massive diff. Reviewers give better feedback.
|
||||
- **Multiple PRs**: When reviewing several PRs, spawn all reviewers in one
|
||||
parallel batch (4 agents for 2 PRs). This is faster than sequential.
|
||||
- **Tyre reads decisions**: Always tell Tyre to read the relevant `decisions/*.md`
|
||||
- **Tyre reads decisions**: Always tell Tyre to read the relevant `governance/**/*.md`
|
||||
files — this grounds the review in project-specific architectural choices.
|
||||
- **Binary/DB files**: Exclude binary files from the diff. Note them in the
|
||||
prompt as "also changed" if relevant.
|
||||
|
||||
@@ -29,7 +29,7 @@ present, because the worktree excluded the wiki directory).
|
||||
**Tyre (Architecture)**
|
||||
- `subagent_type`: `tyre`, `model`: `sonnet`
|
||||
- Prompt: Provide the team directory path, list of changed files, and commit log.
|
||||
Tell Tyre to read the relevant `decisions/*.md` files from the team directory
|
||||
Tell Tyre to read the relevant `governance/**/*.md` files from the team directory
|
||||
first, then review for:
|
||||
- Architectural consistency with project decisions
|
||||
- API/interface design quality
|
||||
@@ -52,7 +52,7 @@ present, because the worktree excluded the wiki directory).
|
||||
**Paula (Narrative Depth)**
|
||||
- `subagent_type`: `paula`, `model`: `sonnet`
|
||||
- Prompt: Provide the team directory path, list of changed files, commit log, and
|
||||
list of relevant `decisions/*.md` files to read. Tell Paula to read all
|
||||
list of relevant `governance/**/*.md` files to read. Tell Paula to read all
|
||||
files from the team directory using the Read tool, then review for:
|
||||
- Narrative quality and character voice consistency
|
||||
- Whether dialogue and monologue feel authentic to the characters
|
||||
@@ -63,7 +63,7 @@ present, because the worktree excluded the wiki directory).
|
||||
**Miri (World Consistency)**
|
||||
- `subagent_type`: `miri`, `model`: `sonnet`
|
||||
- Prompt: Provide the team directory path, list of changed files, commit log, and
|
||||
list of relevant `decisions/*.md` files to read. Tell Miri to read all
|
||||
list of relevant `governance/**/*.md` files to read. Tell Miri to read all
|
||||
files from the team directory using the Read tool, then review for:
|
||||
- Lore accuracy — do facts match established setting?
|
||||
- Internal consistency across files
|
||||
|
||||
@@ -84,7 +84,7 @@ tooling/db/ticket show --brief <id> [<id>...]
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Decisions from `decisions/` domain files become **initiatives**
|
||||
1. Decisions from `governance/` domain files become **initiatives**
|
||||
2. Initiatives break into **epics** (major work areas)
|
||||
3. Epics break into **stories** (user-facing deliverables)
|
||||
4. Stories break into **tasks** (concrete work items)
|
||||
|
||||
@@ -110,8 +110,8 @@ Agent({
|
||||
Decision ref: <decision_ref>
|
||||
|
||||
Your job:
|
||||
1. Read the ticket's decision_ref D/Q-record in decisions/*.md
|
||||
2. Grep for related Q-records in decisions/questions-*.md
|
||||
1. Read the ticket's decision_ref D/Q-record in governance/**/*.md
|
||||
2. Grep for related Q-records in governance/questions/*.md
|
||||
3. Read workshop outcomes if referenced (check docs/workshops/)
|
||||
4. Check whether referenced code, tables, or files actually exist
|
||||
|
||||
|
||||
@@ -96,7 +96,7 @@ When all Round N tasks are complete:
|
||||
Before the user dismisses the team, the following are **hard requirements**:
|
||||
|
||||
1. **User reviews final outcomes** — Present `workshop-outcomes.md` content to the user via AskUserQuestion. Get explicit approval before proceeding to filing.
|
||||
2. **D-records filed** — All new D-records, amendments, and supersessions are written to `decisions/` domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
|
||||
2. **D-records filed** — All new D-records, amendments, and supersessions are written to `governance/` domain files. This is non-negotiable — workshops that produce decisions MUST file them before shutdown.
|
||||
3. **Discussion captured** — Qatux produces final `workshop-outcomes.md` from accumulated notes. Qatux creates or updates diagrams (via `/d2-diagram`) for any new D-records produced by the workshop.
|
||||
4. **Tickets created** — If SI is present, SI creates tickets from decided items and the user reviews the ticket list.
|
||||
5. **User gives explicit go-ahead to dismiss** — Only after steps 1-4 are complete AND the user confirms, send shutdown_request to all agents (qatux and si last).
|
||||
|
||||
Reference in New Issue
Block a user