opencodekit 0.20.4 → 0.20.6

package/dist/template/.opencode/command/iterate.md

@@ -0,0 +1,200 @@
+---
+description: Refine PRD mid-implementation when scope changes, discoveries emerge, or requirements pivot
+argument-hint: "<bead-id> [--scope expand|reduce|pivot] [--reason <text>]"
+agent: build
+---
+
+# Iterate: $ARGUMENTS
+
+Refine a bead's PRD during active implementation. Two-phase process: define what changed, then update spec artifacts and re-derive affected tasks.
+
+> **When to use:** Mid-`/ship` when you discover scope changed, requirements shifted, or a technical discovery invalidates the original plan.
+>
+> **NOT for:** Pre-implementation changes (use `/create` to rewrite the PRD) or post-implementation retrospectives (use `/compound`).
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "prd" });
+skill({ name: "prd-task" });
+```
+
+## Parse Arguments
+
+| Argument    | Default       | Description                        |
+| ----------- | ------------- | ---------------------------------- |
+| `<bead-id>` | required      | The bead being iterated            |
+| `--scope`   | auto-detected | Change type: expand, reduce, pivot |
+| `--reason`  | prompted      | Why the change is needed           |
+
+## Before You Iterate
+
+- **Be certain**: Only iterate if continuing with the current spec would produce wrong output
+- **Don't over-iterate**: Minor adjustments don't need a full iterate cycle — just fix inline during `/ship`
+- **Preserve progress**: Completed tasks stay completed unless explicitly invalidated
+- **Document the delta**: Every change must be traceable to a reason
+
+## Phase 1: Guards
+
+```bash
+br show $ARGUMENTS
+```
+
+Read `.beads/artifacts/$ARGUMENTS/` to check what artifacts exist.
+
+Verify:
+
+- Bead is `in_progress`
+- `prd.md` exists
+- Implementation is partially complete (at least 1 task done or in-progress)
+
+If no tasks are started yet, redirect: "Use `/create --spec-only` to rewrite the PRD instead."
+
+## Phase 2: Assess Change Type
+
+If `--scope` was not provided, determine the change type:
+
+| Type       | Signal                                                  | Example                                   |
+| ---------- | ------------------------------------------------------- | ----------------------------------------- |
+| **expand** | New requirement discovered, additional files needed     | "We also need to handle edge case X"      |
+| **reduce** | Feature is over-scoped, some tasks are unnecessary      | "We don't need the admin panel after all" |
+| **pivot**  | Fundamental approach changed, different solution needed | "REST won't work, switching to WebSocket" |
+
+Ask user to confirm:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Change Type",
+      question: "What kind of spec change is this?",
+      options: [
+        { label: "Expand", description: "Adding scope — new requirements or files" },
+        { label: "Reduce", description: "Removing scope — dropping unnecessary work" },
+        { label: "Pivot", description: "Changing approach — different solution path" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 3: Define the Delta
+
+### Step 1: Capture the change reason
+
+If `--reason` was not provided, ask:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Reason",
+      question: "What triggered this change? (Be specific — this goes into the PRD changelog)",
+      options: [],
+    },
+  ],
+});
+```
+
+### Step 2: Identify affected artifacts
+
+Read the current PRD and list:
+
+- **Tasks completed:** (preserve these unless pivot invalidates them)
+- **Tasks in-progress:** (may need modification)
+- **Tasks not started:** (may need modification, removal, or replacement)
+- **New tasks needed:** (for expand/pivot)
+
+### Step 3: Document the delta
+
+Write a change record to `.beads/artifacts/$ARGUMENTS/iterations.md`:
+
+```markdown
+## Iteration [N] — [date]
+
+**Type:** [expand | reduce | pivot]
+**Reason:** [user-provided reason]
+**Triggered by:** [discovery | user request | technical constraint | external dependency]
+
+### Impact Assessment
+
+| Area  | Before                  | After                     | Action                         |
+| ----- | ----------------------- | ------------------------- | ------------------------------ |
+| Scope | [original scope]        | [new scope]               | [expanded/reduced/pivoted]     |
+| Tasks | [N] total, [M] complete | [N'] total, [M] preserved | [added/removed/modified count] |
+| Files | [original file list]    | [updated file list]       | [new/removed files]            |
+
+### Task Changes
+
+- **Preserved:** [list of completed task titles — unchanged]
+- **Modified:** [list of tasks with what changed]
+- **Removed:** [list of tasks marked obsolete, with reason]
+- **Added:** [list of new tasks]
+```
+
+## Phase 4: Apply Changes
+
+### For Expand:
+
+1. Add new sections/requirements to `prd.md`
+2. Add new tasks at the end of the Tasks section
+3. Mark new tasks with `depends_on` referencing completed tasks if needed
+4. Re-run `prd-task` skill to regenerate `prd.json` with merged task state
+
+### For Reduce:
+
+1. Move removed scope items to "Out-of-Scope" in `prd.md` with note: `[Removed in Iteration N: reason]`
+2. Mark affected tasks by changing their heading from `### Task Title [category]` to `### ~~Task Title~~ [OBSOLETE — Iteration N]` in `prd.md` (don't delete — preserve history). The `prd-task` skill skips headings containing `OBSOLETE` or `INVALIDATED` markers.
+3. Re-run `prd-task` to regenerate `prd.json` (obsolete tasks excluded)
+
+### For Pivot:
+
+1. Archive current PRD section as `## Original Approach (Superseded)` at bottom of file
+2. Rewrite affected sections (Proposed Solution, Requirements, Tasks)
+3. Preserve completed tasks that are still valid
+4. Mark invalidated completed tasks by changing their heading to `### ~~Task Title~~ [INVALIDATED — Iteration N: reason]`
+5. Re-run `prd-task` to regenerate `prd.json`
+
+### Update plan.md (if exists):
+
+If `.beads/artifacts/$ARGUMENTS/plan.md` exists:
+
+1. Add an "## Iteration [N] Changes" section to the plan
+2. Update dependency graph if tasks changed
+3. Re-compute waves for remaining tasks
+
+## Phase 5: Validate
+
+After applying changes:
+
+- [ ] PRD has no `[NEEDS CLARIFICATION]` markers (resolve or add to Open Questions)
+- [ ] All preserved completed tasks are still valid
+- [ ] New/modified tasks have verification steps
+- [ ] `iterations.md` documents the full delta
+- [ ] `prd.json` reflects the updated task state
+
+## Phase 6: Report
+
+```bash
+br comments add $ARGUMENTS "Iteration [N]: [type] — [reason summary]. Tasks: [added/removed/modified] count"
+```
+
+Output:
+
+1. **Change type:** [expand | reduce | pivot]
+2. **Reason:** [brief summary]
+3. **Task changes:** [N] preserved, [M] modified, [K] removed, [J] added
+4. **Files affected:** [updated list]
+5. **Iteration log:** `.beads/artifacts/$ARGUMENTS/iterations.md`
+6. **Next step:** Continue `/ship $ARGUMENTS` with updated spec
+
+## Related Commands
+
+| Need                       | Command            |
+| -------------------------- | ------------------ |
+| Create initial spec        | `/create`          |
+| Continue shipping          | `/ship <id>`       |
+| Review after changes       | `/review-codebase` |
+| Post-implementation review | `/compound <id>`   |

package/dist/template/.opencode/command/plan.md

@@ -18,6 +18,7 @@ Create a detailed implementation plan with TDD steps. Optional deep-planning bet
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 skill({ name: "writing-plans" }); // TDD plan format
 ```
 
@@ -44,12 +45,7 @@ Before touching the PRD or planning anything, load what the codebase already kno
 
 ### Step 1: Search institutional memory
 
-```typescript
-// Search for past decisions, patterns, gotchas related to this work
-memory_search({ query: "<bead-title or feature keywords>", limit: 5 });
-memory_search({ query: "<key technical concept from bead>", type: "bugfix", limit: 3 });
-memory_read({ file: "handoffs/last" }); // Check last session context
-```
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: bugfixes, existing plans (ask user before overwriting).
 
 If relevant observations found: incorporate them directly into the plan. Don't re-solve solved problems.
 
@@ -132,7 +128,10 @@ question({
       header: "Discovery Level",
       question: "Suggested discovery level based on PRD complexity. Proceed?",
       options: [
-        { label: "Deep (Recommended for complex work)", description: "Level 2-3: spawn scout + explore agents" },
+        {
+          label: "Deep (Recommended for complex work)",
+          description: "Level 2-3: spawn scout + explore agents",
+        },
         { label: "Standard", description: "Level 1: quick doc lookup" },
         { label: "Skip research", description: "Level 0: I know the codebase" },
       ],
@@ -318,7 +317,68 @@ Wave 3: C
 - **Each step is 2-5 minutes** — one action per step
 - **Tasks map to PRD tasks**
 
-## Phase 8: Create Child Beads (if --create-beads or L size)
+## Phase 8: Constitutional Compliance Gate
+
+Before executing, scan the plan against AGENTS.md hard constraints. This catches violations before they become implementation bugs.
+
+### Automated Checks
+
+Scan `plan.md` content for these patterns:
+
+| Violation Pattern                                 | AGENTS.md Rule                              | Severity     |
+| ------------------------------------------------- | ------------------------------------------- | ------------ |
+| `git add .` or `git add -A`                       | Multi-Agent Safety: stage specific files    | **CRITICAL** |
+| `--force` push or `force push`                    | Git Safety: never force push main           | **CRITICAL** |
+| `--no-verify`                                     | Git Safety: never bypass hooks              | **CRITICAL** |
+| `as any` or `@ts-ignore` without justification    | Quality Bar: strong typing                  | **WARNING**  |
+| New package/dependency without approval step      | Guardrails: no new deps without approval    | **WARNING**  |
+| Task modifying >3 files without plan confirmation | Guardrails: no surprise edits               | **WARNING**  |
+| `reset --hard` or `checkout .` or `clean -fd`     | Git Restore: never without explicit request | **CRITICAL** |
+| Secret/credential patterns                        | Security: never expose credentials          | **CRITICAL** |
+
+### Check Process
+
+```bash
+# Scan plan for violation patterns (fixed-string mode to avoid regex false positives)
+grep -inF "git add ." .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "git add -A" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF -- "--no-verify" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "force push" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF -- "--force" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "reset --hard" .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "checkout ." .beads/artifacts/$ARGUMENTS/plan.md
+grep -inF "clean -fd" .beads/artifacts/$ARGUMENTS/plan.md
+```
+
+Also check:
+
+- Count files per task: if any task lists >3 files in its `files:` metadata, flag as WARNING
+- Check for `as any` or `@ts-ignore` usage that lacks a documented reason
+- Check if any task adds new dependencies (look for `npm install`, `pnpm add`, `yarn add`, `pip install`, `cargo add`)
+
+### Violation Response
+
+| Severity     | Action                                                             |
+| ------------ | ------------------------------------------------------------------ |
+| **CRITICAL** | Stop. Remove violation from plan. Report to user.                  |
+| **WARNING**  | Flag in plan output. Add confirmation checkpoint to affected task. |
+
+If no violations found, report: `Constitutional compliance: ✓ PASS`
+
+If violations found:
+
+```markdown
+## ⚠️ Constitutional Compliance Check
+
+| #   | Pattern Found        | Location       | Severity | Action                              |
+| --- | -------------------- | -------------- | -------- | ----------------------------------- |
+| 1   | `git add .`          | Task 3, step 2 | CRITICAL | Removed — use specific file staging |
+| 2   | New dependency `zod` | Task 1         | WARNING  | Added approval checkpoint           |
+
+Violations resolved. Plan is compliant.
+```
+
+## Phase 9: Create Child Beads (if --create-beads or L size)
 
 For large work, create child beads for each plan phase:
 
@@ -327,7 +387,7 @@ CHILD=$(br create "[Phase title]" --type task --json | jq -r '.id')
 br dep add $CHILD $ARGUMENTS
 ```
 
-## Phase 9: Report
+## Phase 10: Report
 
 Output:
 
@@ -347,8 +407,8 @@ br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y]
 
 ## Related Commands
 
-| Need           | Command       |
-| -------------- | ------------- |
-| Create spec    | `/create`     |
-| Execute plan   | `/ship <id>`  |
-| Research first | `/research`   |
+| Need           | Command      |
+| -------------- | ------------ |
+| Create spec    | `/create`    |
+| Execute plan   | `/ship <id>` |
+| Research first | `/research`  |

package/dist/template/.opencode/command/pr.md

@@ -10,6 +10,8 @@ agent: build
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "verification-gates" });
 skill({ name: "verification-before-completion" });
 ```
 
@@ -28,14 +30,7 @@ git status --porcelain
 
 If uncommitted changes exist, ask whether to commit first.
 
-Run verification gates. Detect project type and use the appropriate commands:
-
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+Follow the [verification-gates](../skill/verification-gates/SKILL.md) skill protocol. All gates must pass before creating the PR.
 
 Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
 
@@ -45,14 +40,7 @@ If any gate fails, stop. Fix errors first, then run `/pr` again.
 
 ### Memory Grounding
 
-Search memory for relevant decisions, known issues, and prior review findings:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<branch or feature keywords>", limit: 5 });
-```
-
-Include relevant findings in the PR description (e.g., architectural decisions, known limitations).
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Include relevant findings in the PR description.
 
 ### Git Context
 

package/dist/template/.opencode/command/research.md

@@ -14,6 +14,7 @@ Gather information before implementation. Find answers, document findings, stop
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 // For --thorough mode:
 skill({ name: "deep-research" });
 ```
@@ -66,17 +67,7 @@ Read PRD if it exists and extract questions that need answering.
 
 ### Memory Search (Required)
 
-Always search memory before spawning research agents:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<topic keywords>", limit: 10 });
-```
-
-If memory returns relevant findings, use them to:
-- Skip questions already answered
-- Narrow research scope to gaps only
-- Avoid contradicting prior decisions without justification
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Use findings to: skip already-answered questions, narrow scope to gaps only, avoid contradicting prior decisions without justification.
 
 ## Phase 2: Research
 
@@ -130,8 +121,8 @@ Report:
 
 ## Related Commands
 
-| Need          | Command       |
-| ------------- | ------------- |
-| Create + start | `/create`     |
-| Plan details  | `/plan <id>`  |
-| Pick up work   | `/ship <id>`  |
+| Need           | Command      |
+| -------------- | ------------ |
+| Create + start | `/create`    |
+| Plan details   | `/plan <id>` |
+| Pick up work   | `/ship <id>` |

package/dist/template/.opencode/command/resume.md

@@ -12,6 +12,7 @@ Pick up where a previous session left off. Recover context, verify state, contin
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
 ```
 
 ## Phase 1: Verify Task
@@ -33,11 +34,7 @@ If not on the right branch, check out the feature branch. If uncommitted changes
 
 ## Phase 3: Find Handoff
 
-Check for handoff notes in the memory system:
-
-```typescript
-memory_read({ file: "handoffs/$ARGUMENTS" });
-```
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: handoff file by bead ID, session history.
 
 If a handoff exists, it tells you:
 
@@ -46,12 +43,6 @@ If a handoff exists, it tells you:
 - What to do next
 - Any blockers
 
-Also search previous sessions:
-
-```typescript
-find_sessions({ query: "$ARGUMENTS" });
-```
-
 ## Phase 4: Load Artifacts
 
 Read all available context:

package/dist/template/.opencode/command/review-codebase.md

@@ -11,6 +11,7 @@ agent: review
 ```typescript
 skill({ name: "beads" });
 skill({ name: "requesting-code-review" });
+skill({ name: "verification-gates" });
 ```
 
 ## Determine Input Type
@@ -32,13 +33,13 @@ skill({ name: "requesting-code-review" });
 
 ## Available Tools
 
-| Tool         | Use When                                |
-| ------------ | --------------------------------------- |
-| `explore`    | Finding patterns in codebase, prior art |
-| `scout`      | External research, best practices       |
-| `lsp`        | Finding symbol definitions, references  |
-| `tilth_tilth_search` | Finding code patterns |
-| `codesearch` | Real-world usage examples               |
+| Tool                 | Use When                                |
+| -------------------- | --------------------------------------- |
+| `explore`            | Finding patterns in codebase, prior art |
+| `scout`              | External research, best practices       |
+| `lsp`                | Finding symbol definitions, references  |
+| `tilth_tilth_search` | Finding code patterns                   |
+| `codesearch`         | Real-world usage examples               |
 
 ## Phase 1: Gather Context
 
@@ -68,14 +69,7 @@ If bead provided, read `.beads/artifacts/$ID/prd.md` to review against spec.
 
 ## Phase 3: Automated Checks
 
-Detect project type and run the appropriate checks in parallel:
-
-| Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
-| --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
-| Node/TypeScript | `package.json`                | `npm run build`  | `npm test`      | `npm run lint`                | `npm run typecheck` or `tsc --noEmit` |
-| Rust            | `Cargo.toml`                  | `cargo build`    | `cargo test`    | `cargo clippy -- -D warnings` | (included in build)                   |
-| Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
-| Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
+Follow the [verification-gates](../skill/verification-gates/SKILL.md) skill protocol.
 
 Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
 

package/dist/template/.opencode/command/ship.md

@@ -16,6 +16,8 @@ Execute PRD tasks, verify each passes, run review, close the bead.
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-grounding" });
+skill({ name: "workspace-setup" });
 skill({ name: "verification-before-completion" });
 ```
 
@@ -38,27 +40,19 @@ skill({ name: "verification-before-completion" });
 
 ## Available Tools
 
-| Tool      | Use When                                  |
-| --------- | ----------------------------------------- |
-| `explore` | Finding patterns in codebase, prior art   |
-| `scout`   | External research, best practices         |
-| `lsp`     | Finding symbol definitions, references    |
-| `tilth_tilth_search` | Finding code patterns |
-| `task`    | Spawning subagents for parallel execution |
+| Tool                 | Use When                                  |
+| -------------------- | ----------------------------------------- |
+| `explore`            | Finding patterns in codebase, prior art   |
+| `scout`              | External research, best practices         |
+| `lsp`                | Finding symbol definitions, references    |
+| `tilth_tilth_search` | Finding code patterns                     |
+| `task`               | Spawning subagents for parallel execution |
 
 ## Phase 1: Guards
 
 ### Memory Grounding
 
-Search memory for context, prior decisions, and known issues before executing:
-
-```typescript
-memory-search({ query: "$ARGUMENTS" });
-memory-search({ query: "<bead title keywords>", limit: 5 });
-memory-read({ file: "handoffs/last" });
-```
-
-Use findings to avoid re-discovering known issues or repeating failed approaches.
+Follow the [memory-grounding](../skill/memory-grounding/SKILL.md) skill protocol. Focus on: failed approaches to avoid repeating.
 
 ### Bead Validation
 
@@ -85,44 +79,9 @@ br update $ARGUMENTS --status in_progress
 
 Then ask about workspace:
 
-```typescript
-question({
-  questions: [
-    {
-      header: "Workspace",
-      question: "How do you want to set up the workspace?",
-      options: [
-        {
-          label: "Create feature branch (Recommended)",
-          description: "git checkout -b feat/<bead-id>-<title>",
-        },
-        {
-          label: "Use current branch",
-          description: "Work on current branch",
-        },
-      ],
-    },
-  ],
-});
-```
-
-**If feature branch selected:**
-
-Map bead type to branch prefix:
-
-| Bead Type | Branch Prefix |
-| --------- | ------------- |
-| feature   | feat          |
-| bug       | fix           |
-| task      | task          |
-| epic      | epic          |
-
-```bash
-# Example: feat/br-42-add-auth
-git checkout -b $PREFIX/$BEAD_ID-$TITLE_SLUG
-```
+### Workspace Setup
 
-**If current branch:** Continue without branch creation.
+Follow the [workspace-setup](../skill/workspace-setup/SKILL.md) skill protocol.
 
 **If bead is already `in_progress`:** Skip this phase entirely.
 

package/dist/template/.opencode/memory/_templates/prd.md

@@ -1,5 +1,12 @@
 # Beads PRD Template
 
+> **Template Instructions:**
+>
+> - Replace ALL bracketed placeholders with real content
+> - If you cannot fill a section with confidence, use `[NEEDS CLARIFICATION: reason]` instead of guessing
+> - Any `[NEEDS CLARIFICATION]` markers MUST be resolved before planning can proceed
+> - Delete this instruction block after filling the template
+
 **Bead:** br-[id]  
 **Created:** [date]  
 **Status:** Draft | In Review | Approved
@@ -20,11 +27,11 @@ estimated_hours: 2 # Time estimate for planning
 
 ### What problem are we solving?
 
-[Clear description of the problem. Include user impact and business impact.]
+[Clear description of the problem. Include user impact and business impact. If unclear, use [NEEDS CLARIFICATION: what specifically is unknown]]
 
 ### Why now?
 
-[What triggered this work? Cost of inaction?]
+[What triggered this work? Cost of inaction? Use [NEEDS CLARIFICATION] if motivation is unclear]
 
 ### Who is affected?
 
@@ -37,11 +44,11 @@ estimated_hours: 2 # Time estimate for planning
 
 ### In-Scope
 
-- [List what's allowed]
+- [List what's in scope. Use [NEEDS CLARIFICATION] for ambiguous boundaries]
 
 ### Out-of-Scope
 
-- [List what's explicitly off-limits]
+- [List what's explicitly off-limits. Use [NEEDS CLARIFICATION] for unresolved scope questions]
 - [Deferred to future iterations]
 
 ---
@@ -50,7 +57,7 @@ estimated_hours: 2 # Time estimate for planning
 
 ### Overview
 
-[One paragraph describing what this feature does when complete.]
+[One paragraph describing what this feature does when complete. Use [NEEDS CLARIFICATION] for uncertain design decisions]
 
 ### User Flow (if user-facing)
 
@@ -80,6 +87,8 @@ Brief description of what must be true.
 - **Accessibility:** [WCAG level if applicable]
 - **Compatibility:** [constraint if applicable]
 
+> If any requirement is unknown or unresearched, mark it `[NEEDS CLARIFICATION: what needs investigation]` rather than omitting it.
+
 ---
 
 ## Success Criteria
@@ -127,6 +136,8 @@ files:
 | ---------- | ----- | -------- | ------------- |
 | Question 1 | Name  | Date     | Open/Resolved |
 
+> **All `[NEEDS CLARIFICATION]` markers should be converted to entries in this table for tracking.**
+
 ---
 
 ## Tasks

package/dist/template/.opencode/memory/project/user.md

@@ -27,6 +27,12 @@ updated: 2025-01-06
 - Language: TypeScript
 - Linter: oxlint
 
+## Editing Tool Preferences
+
+- **Primary**: `edit` tool (str_replace) and `patch` tool
+- **Secondary/Fallback**: `tilth_tilth_edit` (hash-anchored edits) — only when str_replace fails
+- **Reading/Search**: `tilth_tilth_read` and `tilth_tilth_search` are fine to use freely
+
 ## Rules to Always Follow
 
 - Run `npm run lint:fix` before any commit
@@ -34,5 +40,6 @@ updated: 2025-01-06
 - Don't modify dist/ directly (it's built output)
 - Ask before adding new dependencies
 - Ask before changing .opencode/ structure
+- Ask before schema changes (zod schemas, config shapes)
 - Never commit secrets or .env files
 - Never force push to main