@geraldmaron/construct 1.0.0 → 1.0.2

package/platforms/opencode/config.template.json

@@ -40,10 +40,6 @@
     }
   },
   "mcp": {
-    "cass": {
-      "type": "local",
-      "command": ["npx", "-y", "@modelcontextprotocol/server-memory@latest"]
-    },
     "context7": {
       "type": "local",
       "command": ["npx", "-y", "@upstash/context7-mcp@latest"]
@@ -53,9 +49,9 @@
       "command": ["node", "__CX_TOOLKIT_DIR__/lib/mcp/server.mjs"],
       "environment": {
         "CONSTRUCT_TRACE_BACKEND": "__CONSTRUCT_TRACE_BACKEND__",
-        "LANGFUSE_BASEURL": "__LANGFUSE_BASEURL__",
-        "LANGFUSE_PUBLIC_KEY": "__LANGFUSE_PUBLIC_KEY__",
-        "LANGFUSE_SECRET_KEY": "__LANGFUSE_SECRET_KEY__"
+        "CONSTRUCT_TELEMETRY_URL": "__CONSTRUCT_TELEMETRY_URL__",
+        "CONSTRUCT_TELEMETRY_PUBLIC_KEY": "__CONSTRUCT_TELEMETRY_PUBLIC_KEY__",
+        "CONSTRUCT_TELEMETRY_SECRET_KEY": "__CONSTRUCT_TELEMETRY_SECRET_KEY__"
       }
     }
   },

package/rules/common/agents.md

@@ -1,55 +1,28 @@
 <!--
-rules/common/agents.md — <one-line purpose>
+rules/common/agents.md — platform-agnostic agent orchestration guidance.
 
-<2–6 line summary.>
+Defines when to route to specialist agents, parallel execution rules,
+and multi-perspective analysis patterns. Does not reference specific
+platform agent types or config paths.
 -->
 # Agent Orchestration
 
-## Available Agents
-
-Located in `~/.claude/agents/`:
-
-| Agent | Purpose | When to Use |
-|-------|---------|-------------|
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design | Architectural decisions |
-| tdd-guide | Test-driven development | New features, bug fixes |
-| code-reviewer | Code review | After writing code |
-| security-reviewer | Security analysis | Before commits |
-| build-error-resolver | Fix build errors | When build fails |
-| e2e-runner | E2E testing | Critical user flows |
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| doc-updater | Documentation | Updating docs |
-| rust-reviewer | Rust code review | Rust projects |
-
 ## Immediate Agent Usage
 
-No user prompt needed:
-1. Complex feature requests - Use **planner** agent
-2. Code just written/modified - Use **code-reviewer** agent
-3. Bug fix or new feature - Use **tdd-guide** agent
-4. Architectural decision - Use **architect** agent
+No user prompt needed — match the task to the right specialist:
+1. Complex feature requests - planning specialist
+2. Code just written/modified - code review specialist
+3. Bug fix or new feature - TDD specialist
+4. Architectural decision - architecture specialist
 
 ## Parallel Task Execution
 
-ALWAYS use parallel Task execution for independent operations:
-
-```markdown
-# GOOD: Parallel execution
-Launch 3 agents in parallel:
-1. Agent 1: Security analysis of auth module
-2. Agent 2: Performance review of cache system
-3. Agent 3: Type checking of utilities
-
-# BAD: Sequential when unnecessary
-First agent 1, then agent 2, then agent 3
-```
+ALWAYS use parallel execution for independent operations. Launch multiple specialists concurrently when their work is independent.
 
 ## Multi-Perspective Analysis
 
-For complex problems, use split role sub-agents:
+For complex problems, use multiple specialist perspectives:
 - Factual reviewer
 - Senior engineer
 - Security expert
 - Consistency reviewer
-- Redundancy checker

package/rules/common/beads-hygiene.md

@@ -0,0 +1,75 @@
+<!--
+rules/common/beads-hygiene.md — Beads issue tracker hygiene contract.
+
+Beads is the system of record for durable work in this project. Status drifts
+when issues are not updated alongside the code, so every agent and persona
+operating in Construct treats hygiene as part of the work, not as cleanup.
+Loaded by AGENTS.md, CLAUDE.md, the construct persona, and the engineer /
+operator / planner role overlays.
+-->
+# Beads Hygiene — Project Contract
+
+Beads (`bd`) is the canonical durable tracker for Construct. Beads only earn their keep when their state matches the world. Stale "open" issues pollute `bd ready`, hide real work, and let agents propose work that already shipped. Every agent — human or AI, on any platform — is responsible for keeping the tracker honest.
+
+## When to update beads
+
+| Event | Required action |
+|---|---|
+| About to start non-trivial work | A Beads issue exists. `bd ready` to find or `bd create` if missing. `bd update <id> --claim` before edits. |
+| Work lands on `main` | `bd close <id> --reason="Landed in PR #N — verified: <file:line evidence>"`. Do not wait for someone else to notice. |
+| Direction reverses mid-work | `bd supersede <old-id> --with=<new-id>`. Do not edit the old description in place. |
+| Issue scope expands | Update the description and acceptance criteria in the same change that broadens scope. |
+| A blocker is discovered | Add the dependency with `bd dep add <id> <depends-on>` so the readiness queue reflects reality. |
+| A bead becomes irrelevant | `bd close <id> --reason="No longer needed because <why>"`. Do not leave it open hoping someone closes it later. |
+| An existing memory contradicts current behavior | `bd remember --key <key> "..."` to update in place. Do not let future agents read stale "facts". |
+
+## Pre-work checks (every session)
+
+Run before planning, before claiming work, before proposing changes:
+
+1. `bd ready` — surface unblocked work.
+2. `bd list --status=in_progress` — verify nothing has been left mid-flight by an earlier session.
+3. `bd stale` — surface anything untouched past the staleness window.
+4. Cross-check the open list against `git log --oneline -20 origin/main` — close anything whose work actually landed.
+
+If any of these surface drift, fix it before starting new work. Drift you observe and ignore becomes drift the next agent inherits.
+
+## Post-work checks (every commit / push)
+
+After the code changes land in main:
+
+1. The bead the work was claimed against is closed with evidence in the reason.
+2. Any beads superseded by the change are marked superseded, not left open.
+3. New beads exist for follow-up work that was discovered but not done — file them in the same session, not "later".
+4. `bd doctor` and `bd preflight` should run before push and report clean.
+
+## What goes in a bead
+
+| Field | Standard |
+|---|---|
+| Title | Imperative, scoped, parseable. "PR 3 — `construct intake` CLI" beats "intake CLI". |
+| Description | Why the bead exists + what success looks like. State the new shape directly. Do not preserve a "current behavior must keep working" goal unless the user explicitly asked for migration. |
+| Acceptance criteria | Numbered, binary checks. A reviewer can answer pass/fail without re-reading the description. |
+| Dependencies | Wire `bd dep add` whenever order matters. Implicit ordering rots into parallel work that breaks each other. |
+| Notes | Verification evidence and decisions made *during* the work, not the original framing (description owns that). |
+
+## What does **not** belong in a bead
+
+- Internal-tracker references inside committed artifacts (CHANGELOG, commit messages, code comments, user-facing docs). Bead ids live in the bead, in `bd close --reason`, and in `.cx/context.md`. They do not leak into the public surface.
+- Vague placeholders like "investigate X". Either there is a question to answer (`bd note` it on a parent), or there is concrete work to do (file the concrete work).
+- Multi-phase epics with no children. Either decompose into the actual issues at filing time or mark the parent `[epic]` and file children before claiming.
+
+## Hard rules
+
+- **No claim, no edit.** If you are about to modify files, the bead exists and is claimed by you.
+- **No close before verify.** "Tests pass" without `npm test` evidence is not done. Reason field carries the evidence.
+- **No silent supersede.** Both the old and new bead reference each other; the old's close-reason names the new.
+- **No drift past the session boundary.** If you observed drift but did not close/supersede/file, you have not finished the session.
+
+## Bypass
+
+There is no authorized bypass. Beads hygiene is a release gate. If the tooling is genuinely broken (e.g., dolt lock contention, `bd` crash), state the problem, file a bead for the broken tooling, and use `construct beads ...` lock-aware commands while it is being fixed. "I'll update beads later" is not a valid path.
+
+## Automation
+
+Project-level automation is tracked in the beads queue — auto-close on merge, pre-push `bd preflight` gate, weekly drift report, memory-contradiction detection. Until that ships, hygiene is a per-session discipline.

package/rules/common/code-review.md

@@ -1,59 +1,30 @@
 <!--
-rules/common/code-review.md — <one-line purpose>
+rules/common/code-review.md — when and how to conduct code reviews.
 
-<2–6 line summary.>
+Defines mandatory review triggers, severity levels, approval criteria,
+and references coding-style.md and security.md for checklists.
 -->
 # Code Review Standards
 
-## Purpose
-
-Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
-
 ## When to Review
 
-**MANDATORY review triggers:**
-
+**Mandatory triggers:**
 - After writing or modifying code
 - Before any commit to shared branches
 - When security-sensitive code is changed (auth, payments, user data)
 - When architectural changes are made
 - Before merging pull requests
 
-**Pre-Review Requirements:**
-
-Before requesting review, ensure:
-
-- All automated checks (CI/CD) are passing
-- Merge conflicts are resolved
-- Branch is up to date with target branch
-
-## Review Checklist
-
-Before marking code complete:
+**Pre-review:** CI passing, conflicts resolved, branch up to date.
 
-- [ ] Code is readable and well-named
-- [ ] Functions are focused (<50 lines)
-- [ ] Files are cohesive (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Errors are handled explicitly
-- [ ] No hardcoded secrets or credentials
-- [ ] No console.log or debug statements
-- [ ] Tests exist for new functionality
-- [ ] Test coverage meets 80% minimum
-
-## Security Review Triggers
-
-**STOP and use security-reviewer agent when:**
+## Review Workflow
 
-- Authentication or authorization code
-- User input handling
-- Database queries
-- File system operations
-- External API calls
-- Cryptographic operations
-- Payment or financial code
+1. `git diff` to understand changes
+2. Security checklist (see [security.md](security.md))
+3. Code quality checklist (see [coding-style.md](coding-style.md))
+4. Run tests, verify coverage >= 80%
 
-## Review Severity Levels
+## Severity Levels
 
 | Level | Meaning | Action |
 |-------|---------|--------|
@@ -62,68 +33,8 @@ Before marking code complete:
 | MEDIUM | Maintainability concern | **INFO** - Consider fixing |
 | LOW | Style or minor suggestion | **NOTE** - Optional |
 
-## Agent Usage
-
-Use these agents for code review:
-
-| Agent | Purpose |
-|-------|---------|
-| **code-reviewer** | General code quality, patterns, best practices |
-| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
-| **typescript-reviewer** | TypeScript/JavaScript specific issues |
-| **python-reviewer** | Python specific issues |
-| **go-reviewer** | Go specific issues |
-| **rust-reviewer** | Rust specific issues |
-
-## Review Workflow
-
-```
-1. Run git diff to understand changes
-2. Check security checklist first
-3. Review code quality checklist
-4. Run relevant tests
-5. Verify coverage >= 80%
-6. Use appropriate agent for detailed review
-```
-
-## Common Issues to Catch
-
-### Security
-
-- Hardcoded credentials (API keys, passwords, tokens)
-- SQL injection (string concatenation in queries)
-- XSS vulnerabilities (unescaped user input)
-- Path traversal (unsanitized file paths)
-- CSRF protection missing
-- Authentication bypasses
-
-### Code Quality
-
-- Large functions (>50 lines) - split into smaller
-- Large files (>800 lines) - extract modules
-- Deep nesting (>4 levels) - use early returns
-- Missing error handling - handle explicitly
-- Mutation patterns - prefer immutable operations
-- Missing tests - add test coverage
-
-### Performance
-
-- N+1 queries - use JOINs or batching
-- Missing pagination - add LIMIT to queries
-- Unbounded queries - add constraints
-- Missing caching - cache expensive operations
-
 ## Approval Criteria
 
 - **Approve**: No CRITICAL or HIGH issues
 - **Warning**: Only HIGH issues (merge with caution)
 - **Block**: CRITICAL issues found
-
-## Integration with Other Rules
-
-This rule works with:
-
-- [testing.md](testing.md) - Test coverage requirements
-- [security.md](security.md) - Security checklist
-- [git-workflow.md](git-workflow.md) - Commit standards
-- [agents.md](agents.md) - Agent delegation

package/rules/common/coding-style.md

@@ -1,7 +1,8 @@
 <!--
-rules/common/coding-style.md — <one-line purpose>
+rules/common/coding-style.md — language-agnostic coding standards.
 
-<2–6 line summary.>
+Covers immutability, core principles (KISS/DRY/YAGNI), file organization,
+error handling, input validation, naming conventions, and quality checklist.
 -->
 # Coding Style
 
@@ -67,7 +68,8 @@ ALWAYS validate at system boundaries:
 - Booleans: prefer `is`, `has`, `should`, or `can` prefixes
 - Interfaces, types, and components: `PascalCase`
 - Constants: `UPPER_SNAKE_CASE`
-- Custom hooks: `camelCase` with a `use` prefix
+
+> **Language note**: Naming conventions may be overridden by language-specific rules (e.g. snake_case in Python/Go).
 
 ## Code Smells to Avoid
 

package/rules/common/comments.md

@@ -1,139 +1,58 @@
 <!--
-rules/common/comments.md — canonical comment policy for the Construct repo.
+rules/common/comments.md — Construct comment convention for JS/TS/MJS source files.
 
-Applies to every file in this repository, including generated agent output.
-Enforced by `construct lint:comments`, the comment-lint PostToolUse hook,
-and CI. Authoring agents must follow this policy without needing reminders.
+Defines the two allowed comment forms (file header, section context block) and
+what is never allowed (inline narration, trailing comments, mid-function notes).
+Enforced by lib/hooks/comment-lint.mjs and tests/hooks-budget.test.mjs.
 -->
+# Comment Convention
 
-# Comment Policy
+Two forms are allowed. Everything else is deleted.
 
-Construct treats comments as durable documentation, not scratch notes. This file is the single source of truth. Every change to Construct — manual or agent-driven — must respect it.
+## File header
 
-## 1. File header block (required)
-
-Every file listed below must start with a header block that states the file's path, a one-line purpose, and a short summary of what it does, who calls it, and any side effects.
-
-**Scope:**
-
-- `bin/**/*` — executable entrypoints
-- `lib/**/*.mjs` — runtime, hooks, server, MCP
-- `sync-agents.mjs`
-- `tests/**/*.mjs`
-- `personas/**/*.md`
-- `skills/**/*.md`
-- `rules/**/*.md`
-- `commands/**/*.md`
-- Generated platform output under `platforms/claude/agents/` and `platforms/opencode/`
-- Scripts under `.github/**` and any top-level shell/Node script
-
-**Format — JavaScript / Node:**
+One `/** */` block at the top of every file. Describes module purpose, key behaviors, and non-obvious constraints. Written once; updated only when the module's contract changes.
 
 ```js
 /**
- * <relative/path.mjs> — <one-line purpose>
+ * lib/observation-store.mjs — hybrid BM25 + cosine ranking over in-tree vector index.
  *
- * <2–6 line summary: what it does, who calls it, key side effects or
- * dependencies a reader would need to know before touching it.>
+ * Writes are append-only. Reads fan out to both stores and merge by max score.
+ * IDF is recomputed per query — acceptable at current corpus size.
  */
 ```
 
-**Format — Markdown:**
-
-```html
-<!--
-<relative/path.md> — <one-line purpose>
+## Section context block
 
-<2–6 line summary matching the JS variant.>
--->
-```
-
-**Format — Shell:**
-
-```bash
-# <relative/path.sh> — <one-line purpose>
-#
-# <2–6 line summary.>
-```
-
-The linter extracts the path from the block's first line and verifies it matches the file's actual location.
-
-## 2. Section comments (allowed, kept short)
-
-Inside a file, a one-line section comment is fine when it genuinely helps navigation:
+A comment block immediately before a logical section, followed by a blank line, then the code. Used only when the section's purpose is not obvious from the function or variable names alone.
 
 ```js
-// --- model selection ---
-```
-
-Do not write multi-line section banners. Do not repeat what the code immediately below already says.
-
-## 3. Inline comments
-
-Default to no inline comment. Only write one when the *why* is non-obvious: a hidden constraint, an invariant, a workaround for a specific bug that would surprise a reader, or a subtle ordering requirement.
-
-A comment that describes *what* the code does is almost always noise — the code already says that. Delete it.
+// BM25 is unbounded; normalize against its own max so it merges fairly with cosine [0,1].
 
-## 4. Banned patterns
-
-The linter flags these as warnings. Agents must not introduce them.
-
-### Point-in-time references
-
-Comments decay. These phrases tie a comment to a moment that the reader can no longer verify:
-
-- `added` / `added for` / `added recently`
-- `new:` / `recently` / `just` / `now`
-- `previously` / `we used to` / `no longer`
-- `removed` / `deleted` (as narration, not instruction)
-- `in this PR` / `for this task` / `for the X flow`
-- absolute dates (`2024-…`, `Jan 2025`, etc.) unless tied to a real external deadline
-
-### Caller references
-
-The reader can grep for callers. Comments that claim to enumerate them rot:
-
-- `used by X` / `called from Y` / `only consumer is Z`
-
-*Exception:* the file-header block may list primary consumers when the list is short and load-bearing (see `lib/cli-commands.mjs` for the pattern).
-
-### Issue / PR / ticket references
-
-These belong in commit messages and PR bodies, not in source:
-
-- `#\d+` / `GH-\d+` / `JIRA-\d+`
-- `fixes #…` / `closes #…` / `see ticket …`
+const bm25Max = bm25Scored[0]?.score || 1;
+for (const item of bm25Scored) { ... }
+```
 
-### Trailing "why" comments on self-evident code
+The blank line between the comment and the code is required. It signals "this comment describes the block below", not "this comment describes the line above".
 
-If the code reads cleanly, leave it alone:
+## What is never allowed
 
-```js
-const total = subtotal + tax; // add tax   ← delete this
-```
+- **Inline trailing comments** — `const x = 1; // increment` — delete them
+- **Mid-function narration** — a comment in the middle of a function body that describes what the next line does — delete it; rename the variable or extract a function instead
+- **Between-group labels** — `// Language patterns`, `// Dashboard`, `// Step 1:` — delete them
+- **Narrative voice** — `// We weight BM25`, `// Now test the keys`, `// This correctly scores` — delete them
+- **Point-in-time notes** — `// X removed`, `// previously`, `// no longer` — belongs in git log
+- **Noise sentinels** — `// ok`, `// best effort`, `// skip` — delete them; use `/* non-critical */` inline only when the catch clause would otherwise look like a bug
 
-### TODO / FIXME without context
+## SLA annotations (hooks only)
 
-TODOs without an owner and a reason are abandoned the moment they are written. Required shape:
+`@p95ms` and `@maxBlockingScope` are required on every hook file header. They are metadata, not narration, and are exempt from the above rules.
 
 ```js
-// TODO(owner): <what and why> — <condition that resolves it>
+// @p95ms 40  @maxBlockingScope PreToolUse
 ```
 
-## 5. Generated files
-
-Files under `platforms/claude/agents/` and `platforms/opencode/` that are generated output must carry the canonical "Generated by construct sync" banner produced by `sync-agents.mjs`. Hand-edits to these files are rejected; regenerate instead.
-
-## 6. Enforcement
-
-| Violation | Level | Enforced by |
-|---|---|---|
-| Missing file header in a scoped path | error | `construct lint:comments`, CI |
-| Banned pattern in a comment | warning | `construct lint:comments`, PostToolUse hook |
-| Hand-edit to a generated file | error | `sync-agents.mjs` regeneration + CI |
-
-`construct lint:comments --fix` adds stub headers to files missing one. Banned patterns must be resolved by hand — the linter refuses to guess at the author's intent.
+## Rule of thumb
 
-## 7. Why this is strict
+Delete the comment. If the section becomes harder to understand, the comment earns its place — as a block before it, with a blank line after. If it reads just as clearly without, it stays deleted.
 
-The repo generates configs for every downstream tool. A point-in-time comment in a persona file becomes a point-in-time comment in every Claude Code, OpenCode, Codex, and Copilot install of Construct. The cost of a lazy comment is multiplied across every surface.

package/rules/common/commit-approval.md

@@ -0,0 +1,53 @@
+<!--
+rules/common/commit-approval.md — conversational approval rule for mutating git operations.
+
+Behavioral rule, not a hook. The agent asks and waits for a yes; the user
+replies in chat. Infrastructure stays out of the way.
+-->
+# Commit Approval
+
+Construct does not commit, push, or merge without the user explicitly saying yes in the current conversation.
+
+## The rule
+
+Before running any of these Bash tool calls:
+
+- `git commit` (including `git commit --amend`)
+- `git push`
+- `gh pr merge`
+
+The agent must:
+
+1. **State the working branch** so the user sees the scope.
+2. **Show the proposed action verbatim** — for a commit, the full proposed message (subject and body) formatted exactly as it will appear in `git log`. For a push, the target refspec. For a merge, the PR number and merge mode (`--squash`, `--rebase`, etc.).
+3. **Ask for confirmation** and wait for a yes before executing.
+
+A yes from the user in chat is the approval. No marker file, no CLI command, no special syntax.
+
+The standard proposal format for a commit:
+
+```
+Branch: <name>
+Proposed commit message:
+
+  type(scope): subject
+
+  Optional body explaining the why.
+
+Run `git commit`?
+```
+
+Then stop and wait.
+
+## Exceptions
+
+- **The user explicitly tells the agent to run a defined sequence** ("commit, push, and merge when ready"). That single yes covers the named batch — but only the actions named, in the order named. A new commit triggered later (e.g. by a CI fix or follow-up edit) is its own approval gate.
+- **Read-only git operations** (`git status`, `git log`, `git diff`, `git fetch`, `git branch`, `git show`) don't need approval.
+
+A "yes" from earlier in the session does NOT carry forward to subsequent commits. Each new commit message must be shown and approved.
+
+## Why this is a rule, not a hook
+
+A hook that blocked every commit turned out to be over-restrictive — it required a separate command invocation to write a marker file each time, which added friction without much safety beyond the agent just following the rule. The agent is the one producing commit messages; asking in chat is the right interface.
+
+If the agent ever commits without asking, that's a correctness bug. Surface it in the session and raise a follow-up to catch the regression.

package/rules/common/cx-agent-routing.md

@@ -59,3 +59,4 @@ When a request matches the trigger patterns below, automatically route to the co
 6. **Explorer for unknown territory.** When the codebase area is unfamiliar, route to cx-explorer first.
 7. **Unclear requirements always stop at planning.** If missing acceptance criteria or ambiguous scope, route to cx-product-manager or cx-ux-researcher before implementation.
 8. **Read once per conversation.** No need to re-read this file if already loaded.
+9. **Research follows the common research policy.** Research, evidence synthesis, and doc-grounding tasks should apply `rules/common/research.md` before treating claims as decision-ready.

package/rules/common/development-workflow.md

@@ -1,49 +1,31 @@
 <!--
-rules/common/development-workflow.md — <one-line purpose>
+rules/common/development-workflow.md — feature implementation pipeline.
 
-<2–6 line summary.>
+Defines the research-plan-TDD-review-commit workflow that runs before
+git operations. References testing.md, code-review.md, git-workflow.md.
 -->
 # Development Workflow
 
-> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
-
-The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
-
 ## Feature Implementation Workflow
 
 0. **Research & Reuse** _(mandatory before any new implementation)_
-   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
-   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
-   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
-   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
-   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
-   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
-
-1. **Plan First**
-   - Use **planner** agent to create implementation plan
-   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
-   - Identify dependencies and risks
-   - Break down into phases
-
-2. **TDD Approach**
-   - Use **tdd-guide** agent
-   - Write tests first (RED)
-   - Implement to pass tests (GREEN)
-   - Refactor (IMPROVE)
-   - Verify 80%+ coverage
-
-3. **Code Review**
-   - Use **code-reviewer** agent immediately after writing code
-   - Address CRITICAL and HIGH issues
-   - Fix MEDIUM issues when possible
-
-4. **Commit & Push**
-   - Detailed commit messages
-   - Follow conventional commits format
-   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
-
-5. **Pre-Review Checks**
-   - Verify all automated checks (CI/CD) are passing
-   - Resolve any merge conflicts
-   - Ensure branch is up to date with target branch
-   - Only request review after these checks pass
+   - **Search existing code first:** Look for existing implementations, templates, and patterns before writing anything new.
+   - **Check docs:** Confirm API behavior, package usage, and version-specific details before implementing.
+   - **Check package registries:** npm, PyPI, crates.io before writing utility code.
+   - Prefer adopting a proven approach over writing net-new code.
+
+1. **Plan** - Break into phases; identify dependencies and risks.
+
+2. **TDD** - Write tests first (RED), implement (GREEN), refactor (IMPROVE). See [testing.md](testing.md).
+
+3. **Code Review** - Review immediately after writing. See [code-review.md](code-review.md).
+
+3.5. **Docs** _(mandatory for any user-facing change)_
+   - If you added or changed a CLI command, API endpoint, config option, or architecture boundary: update `docs/concepts/architecture.md` and create or update the relevant `docs/cookbook/` recipe.
+   - If you added a CLI command, ensure the cookbook index links to a recipe for it.
+   - Run `construct docs:update` to regenerate AUTO-managed regions.
+   - A change is not DONE if a user-facing capability exists with no documentation.
+
+4. **Commit** - Conventional commits format. See [git-workflow.md](git-workflow.md).
+
+5. **Pre-Review Checks** - CI passing, conflicts resolved, branch synced.