GW2 Priory — Project Constitution

An agentic companion for Guild Wars 2 (planning & optimization). Flagship MVP: a legendary crafting planner.

The real goal is to practise spec-driven development with an AI agent. The tool is the vehicle. When the two conflict, the workflow wins.

The workflow (non-negotiable)

Each feature lives in specs/NNN-<slug>/, copied from specs/_template/. All four artifacts are committed — a plan or task list that only exists in chat is lost.

• 0 · Scaffold — allocate the number, then create the branch and an isolated worktree with EnterWorktree and enter it, and scaffold specs/NNN-<slug>/ inside it. Isolation is here, at the start, so a second feature can be opened without disturbing the first; the shared tree never changes branch. Steps 1–6 run in the worktree.
• 1 · Spec — spec.md, agreed before any code. Given-When-Then scenarios, measurable technology-agnostic success criteria. Unresolved points are marked [NEEDS CLARIFICATION: …] rather than assumed, and block step 1.5. Once agreed, spec.md is committed and pushed before discovery, so the branch reaches the remote early; each later artifact is committed and pushed as it lands.
• 1.5 · Discovery — research.md. Every claim the spec rests on is confirmed against the codebase and the outside world before approval, with cited evidence. [NEEDS VERIFICATION: …] marks what only reality can answer; a refuted claim sends the spec back to step 1 rather than being patched.
• 2 · Plan — plan.md, written in plan mode and approved before a line is written.
• 3 · Tasks — tasks.md: small, independently verifiable steps.
• 4 · Implement — entered only through plan mode: before any implementation code is written, the agent enters plan mode, presents the implementation plan, and starts only once the human approves it. Then the agent writes, the human reviews the diff.
• 5 · Verify — types + tests + running the app.
• 6 · Capture — decisions land in a spec or in docs/, not in chat history.
• Cleanup — once the PR merges, remove the worktree and branch from the main tree: git worktree remove .claude/worktrees/NNN-<slug>, git branch -D NNN-<slug>, git worktree prune. finishing-a-development-branch does not cover .claude/worktrees/, so this is done by hand.

Gates

Three hard stops. Only the human releases them.

• The only way to produce a plan is for spec.md's status to be approved, with every [NEEDS CLARIFICATION] resolved and every [NEEDS VERIFICATION] given a verdict in research.md.
• The only way to produce tasks is for plan.md's status to be approved.
• The only way to begin implementation is through plan mode: the agent enters plan mode, presents the implementation plan, and writes no implementation code until the human approves it. Plan mode before code is mandatory, even when tasks.md is already approved.

Each artifact is produced alone, then handed over for approval. Writing plan.md and tasks.md in one breath defeats the gate between them.

Status is set by the human. The agent never sets it on its own initiative, and never infers approval from enthusiasm. Transcribing a status on an explicit instruction is allowed — and the agent says that is what it did, so the record shows who decided.

Asked to cross a closed gate, the agent refuses and names what is unresolved — which markers, or which status. A refusal without a reason is indistinguishable from a malfunction.

No code without a spec and an approved plan

Exactly two exceptions. Anything else, pushing back is correct behaviour.

1. Bug fixes. superpowers:systematic-debugging to find the root cause, then a failing regression test, then the fix, then step 5. No spec directory. The exception keeps small fixes cheap; it is not a route around TDD or review.
2. Discovery spikes (step 1.5). Throwaway code that answers a [NEEDS VERIFICATION]: run outside the repo, discarded once it has answered, and its finding recorded in research.md. A spike that survives into the working tree has become implementation, and implementation is gated.

Techniques

Each step is carried out by a named superpowers skill, so two runs of the same step produce comparably structured work. Using the named technique is mandatory within a step.

Step	Technique
0 · Scaffold	superpowers:using-git-worktrees (isolation; the numbering/templating is this project's own bookkeeping)
1 · Spec	superpowers:brainstorming
1.5 · Discovery	this project's own; superpowers:dispatching-parallel-agents when the questions are independent
2 · Plan	superpowers:writing-plans — header half, plan.md only
3 · Tasks	superpowers:writing-plans — task half, tasks.md
4 · Implement	superpowers:subagent-driven-development, with superpowers:test-driven-development inside every task and superpowers:systematic-debugging on any surprise
5 · Verify	superpowers:verification-before-completion, then superpowers:requesting-code-review and superpowers:receiving-code-review
6 · Capture	superpowers:finishing-a-development-branch

Long-form step summaries live in specs/001-workflow-tooling/spec.md. They are not repeated here — this file is read every session and its length is a running cost.

Path overrides. brainstorming and writing-plans default to date-named paths under docs/superpowers/. Both state that user preferences override that default, and this is that preference: every artifact is written to specs/NNN-<slug>/, named spec.md, research.md, plan.md, tasks.md. Nothing is written to docs/superpowers/ — a test asserts the count there stays at zero.

Precedence. Skills override default behaviour; this constitution overrides skills. Where a skill and this file conflict, the constitution wins — and the agent must say which skill instruction it is overriding, rather than resolving it quietly. A conflict nobody hears about is indistinguishable from one nobody noticed.

Definition of done

• Typecheck clean, tests pass.
• Every acceptance scenario and success criterion in the spec is covered by a test whose name traces to it, recorded in the spec's traceability table.
• No any, no unexplained escape hatches.
• The human has reviewed the diff.
• The spec's status is moved to implemented inside the feature branch — part of the PR diff, before the merge, never as a separate edit to main afterward. The human still decides it; the agent transcribes it into the branch so the status transition is reviewed and merged with the work it describes.

Conventions

• Branch and PR per spec: NNN-<slug>. CI green before merge.
• Commits: imperative, scoped (api:, web:, specs:, ci:).

Reference

• docs/project-brief.md — what we're building and why (source of truth).
• docs/architecture/stack.md — stack, infra, caching, external API rules, out-of-scope decisions.
• docs/architecture/typescript.md — TypeScript rules.
• docs/architecture/workflow-tooling.md — setup, plugin version posture, hook cost.
• docs/architecture/monorepo.md — workspace wiring: source packages, workspace:*, tsconfig split, Biome.
• docs/architecture/ci.md — CI pipeline, branch-protection enforcement, toolchain-pin posture.
• docs/architecture/deploy.md — Render deploy shape, the one-time GitHub connection, free-tier trade-offs, verification log.
• docs/architecture/domain.md — domain vocabulary and hard facts.
• docs/architecture/gw2-api.md — GW2 API v2 client facts: rate limit, 199 batch cap, 206/404 semantics, response shapes.
• docs/architecture/nestjs.md — apps/api code shape: feature-module layout, thin controllers, the DI value-import rule, Zod-first contract, the GW2 client boundary, error/testing conventions.
• docs/architecture/react.md — apps/web code shape: feature-folder layout, naming, Suspense-only data flow, the enforcement table.
• docs/architecture/design-system.md — apps/web visual vocabulary: rarity tokens, semantic tokens, tokens-never-literals.