diff --git a/.claude/agents/trellis-check.md b/.claude/agents/trellis-check.md index 14334f2..f502410 100644 --- a/.claude/agents/trellis-check.md +++ b/.claude/agents/trellis-check.md @@ -21,7 +21,7 @@ You are already the `trellis-check` sub-agent that the main session dispatched. Look for the `` marker in your input above. - **If the marker is present**: task artifacts, spec, and research files have already been auto-loaded for you above. Proceed with the check work directly. -- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: `, then Read `/check.jsonl`, each listed file, `/prd.md`, `/design.md` if present, and `/implement.md` if present before doing the work. +- **If the marker is absent**: use the task path and scope in the dispatch brief. Read existing `check.jsonl` entries and task artifacts when present. For taskless work, use the brief and relevant specs directly; missing optional artifacts do not block review. ## Context @@ -38,11 +38,11 @@ Before checking, read: 2. **Review task artifacts** - Check changes against prd.md, design.md if present, and implement.md if present 3. **Check against specs** - Verify code follows guidelines 4. **Self-fix** - Fix issues yourself, not just report them -5. **Run verification** - typecheck and lint +5. **Run verification** - checks proportionate to the affected behavior and project contracts ## Important -**Fix issues yourself**, don't just report them. +Fix task-related issues when the dispatch authorizes fixes. A read-only review returns findings without edits. Preserve unrelated changes and do not broaden the task to repair pre-existing failures. You have write and edit tools, you can modify code directly. @@ -79,9 +79,9 @@ After finding issues: ### Step 4: Run Verification -Run project's lint and typecheck commands to verify changes. +Run applicable checks for the affected code or instruction surface; lint/typecheck are not required for prose-only changes. -If failed, fix issues and re-run. +After authorized fixes, rerun affected checks. Broaden only for a concrete unresolved concern; report persistent environment or unrelated failures rather than retrying indefinitely. --- diff --git a/.claude/agents/trellis-implement.md b/.claude/agents/trellis-implement.md index 333bf73..3558427 100644 --- a/.claude/agents/trellis-implement.md +++ b/.claude/agents/trellis-implement.md @@ -21,7 +21,7 @@ You are already the `trellis-implement` sub-agent that the main session dispatch Look for the `` marker in your input above. - **If the marker is present**: prd / spec / research files have already been auto-loaded for you above. Proceed with the implementation work directly. -- **If the marker is absent**: hook injection didn't fire (Windows + Claude Code, `--continue` resume, fork distribution, hooks disabled, etc.). Find the active task path from your dispatch prompt's first line `Active task: `, then Read `/implement.jsonl`, each listed file, `/prd.md`, `/design.md` if present, and `/implement.md` if present before doing the work. +- **If the marker is absent**: use the task path and scope in the dispatch brief. Read existing `implement.jsonl` entries and task artifacts when present. For authorized taskless work, use the brief and relevant specs directly; do not create missing manifests or repeat planning solely to satisfy context loading. ## Context @@ -75,7 +75,7 @@ Read the task's prd.md, design.md if present, and implement.md if present: ### 4. Verify -Run project's lint and typecheck commands to verify changes. +Run checks applicable to the changed behavior and relevant project contracts. Code changes may require lint/typecheck; prose-only work needs consistency and relevant parser checks. Reuse valid checks on unchanged state and report environmental blockers separately from regressions. --- diff --git a/.claude/agents/trellis-research.md b/.claude/agents/trellis-research.md index 916686c..4858aa8 100644 --- a/.claude/agents/trellis-research.md +++ b/.claude/agents/trellis-research.md @@ -1,7 +1,7 @@ --- name: trellis-research description: | - Code and tech search expert. Finds files, patterns, and tech solutions, and PERSISTS every finding to the current task's research/ directory. No code modifications outside that directory. + Code and tech search expert. Finds files, patterns, and technical evidence within a bounded research brief. Persists findings when the caller needs durable output; does not modify application code. tools: Read, Write, Glob, Grep, Bash, Skill, mcp__* --- # Research Agent @@ -10,9 +10,9 @@ You are the Research Agent in the Trellis workflow. ## Core Principle -**You do one thing: find, explain, and PERSIST information.** +**Find and explain the evidence needed by the research brief.** -Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure — the caller cannot read them next session. +Return concise findings with source locations. Persist expensive-to-recover evidence or an explicitly requested research artifact under the caller's task research directory. A brief read-only lookup can return directly; file count does not establish research quality. --- @@ -20,8 +20,8 @@ Conversations get compacted; files don't. Every research output MUST end up as a 1. **Internal Search** — locate files/components, understand code logic, discover patterns (Glob, Grep, Read) 2. **External Search** — library docs, API references, best practices (web search) -3. **Persist** — write each research topic to `{TASK_DIR}/research/.md` -4. **Report** — return file paths + one-line summaries to the main agent (not full content) +3. **Persist when useful** — write durable output to `{TASK_DIR}/research/.md` when requested or needed +4. **Report** — return key findings, evidence locations, material gaps, and any artifact paths --- @@ -29,9 +29,9 @@ Conversations get compacted; files don't. Every research output MUST end up as a ### Step 1: Resolve Current Task -Run `python3 ./.trellis/scripts/task.py current --source` → active task path. If no active task is set, ask the user where to write output; do NOT guess. +Use the task path in the dispatch brief first; inspect `task.py current --source` only when needed. If no task/output path is provided, return findings to the caller. Ask the supervising agent for a path only if a file deliverable is required; do not interrupt the user for routine dispatch context. -Ensure `{TASK_DIR}/research/` exists: +When a file deliverable needs it, ensure `{TASK_DIR}/research/` exists: ```bash mkdir -p /research @@ -47,17 +47,17 @@ Run independent searches in parallel (Glob + Grep + web) for efficiency. ### Step 4: Persist Each Topic -For each distinct research topic, Write a markdown file at `{TASK_DIR}/research/.md`. Use the File Format below. +When durable output is required, write the relevant findings at `{TASK_DIR}/research/.md`. Combine related topics when clearer and use only applicable sections of the file format below. ### Step 5: Report to Main Agent -Reply with ONLY: +Reply with: -- List of files written (paths relative to repo root) -- One-line summary per file +- Findings with concrete source paths/lines or URLs +- Any files written and their purpose - Any critical caveats that the main agent needs to know right now -Do NOT paste full research content into the reply. The files are the contract. +Avoid duplicating lengthy saved artifacts. A concise chat response satisfies a read-only research brief when no durable artifact was requested. --- @@ -125,13 +125,13 @@ Each `{TASK_DIR}/research/.md` should follow: - Provide specific file paths and line numbers - Quote actual code snippets -- Persist every topic to its own file -- Return file paths in your reply, not the full content +- Persist durable evidence when useful or requested +- Return the evidence needed for the caller's next decision - Mark "not found" explicitly when searches come up empty ### DON'T - Don't write code or modify files outside `{TASK_DIR}/research/` - Don't guess uncertain info -- Don't paste full research text into the reply (files are the deliverable) +- Don't replace useful findings with a demand to create a task or choose an output path - Don't propose improvements or critique implementation (that's not your role) diff --git a/.claude/commands/trellis/continue.md b/.claude/commands/trellis/continue.md index 1f7a9e6..b0d1d7d 100644 --- a/.claude/commands/trellis/continue.md +++ b/.claude/commands/trellis/continue.md @@ -1,56 +1,32 @@ # Continue Current Task -Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`. +Resume the first unfinished applicable step in `.trellis/workflow.md`. Preserve the original objective, accepted decisions, and existing authorization. A status or phase change does not require another approval. ---- - -## Step 1: Load Current Context +## Load Context ```bash python3 ./.trellis/scripts/get_context.py -``` - -Confirms: current task, git state, recent commits. - -## Step 2: Load the Phase Index - -```bash python3 ./.trellis/scripts/get_context.py --mode phase ``` -Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping. +Inspect current task, relevant artifacts, git state, and prior authorization. A request to continue an implementation task resumes implementation. If the prior scope was explicitly planning-only or a consequential decision remains unresolved, keep that boundary and continue independent preparation. -## Step 3: Decide Where You Are +## Route by Remaining Work -`get_context.py` shows the active task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation. +- No active task: follow request triage; reuse/create a suitable task when useful or proceed inline for taskless work. Do not ask for process consent. +- `planning` with insufficient goal/acceptance: **1.1**, inspecting evidence before clarifying consequential gaps. +- `planning` with sufficient scope/acceptance: **1.4**, run `task.py start` and proceed if implementation is authorized. Extra documents are needed only for a concrete purpose; JSONL context is needed only for agents actually consuming it. +- `in_progress` with implementation unfinished: **2.1**. +- Implementation done but required verification missing: **2.2**. +- Verification passed: **3.3** assess useful spec updates, **3.4** perform authorized commits, then **3.5** execute wrap-up. +- `completed` but not archived: verify acceptance and run authorized finish-work steps. Never archive merely because the status says completed. -- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`) -- `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`. -- `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3** -- `status=planning` + required artifacts complete + required jsonl curated or inline mode → **1.4** (ask for start review; only run `task.py start` after user confirms) -- `status=in_progress` + implementation not started → **2.1** -- `status=in_progress` + implementation done, not yet checked → **2.2** -- `status=in_progress` + check passed → **3.3** (spec update) → **3.4** (commit) -- `status=completed` (rare; usually archived immediately) → archive flow +Skip applicable steps whose outputs are already valid. Revisit only facts affected by new evidence or scope; do not restart planning or repeat passing checks without cause. -Phase rules (full detail in `.trellis/workflow.md`): - -1. Run steps **in order** within a phase — `[required]` steps must not be skipped -2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`. -3. You may go back to an earlier phase if discoveries require it - -## Step 4: Load the Specific Step - -Once you know which step to resume at: +## Execute ```bash -python3 ./.trellis/scripts/get_context.py --mode phase --step --platform claude +python3 ./.trellis/scripts/get_context.py --mode phase --step ``` -Follow the loaded instructions. After each `[required]` step completes, move to the next. - ---- - -## Reference - -Full workflow and detailed phase steps live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there. +Load the relevant guidance and keep progressing to the requested outcome. Use available skills/tools; unavailable slash commands or agent types have an inline equivalent. Report an exact blocker only after independent authorized work is done. Local completion, commits, review, merge, and deployment are separate states. diff --git a/.claude/commands/trellis/finish-work.md b/.claude/commands/trellis/finish-work.md index ab751c6..830e1fe 100644 --- a/.claude/commands/trellis/finish-work.md +++ b/.claude/commands/trellis/finish-work.md @@ -1,66 +1,45 @@ # Finish Work -Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command. +Complete the current request's authorized wrap-up. Check acceptance before task bookkeeping; a session ending or a commit existing does not establish task completion. Apply `.trellis/workflow.md` and AGENTS.md for authorization, branches, and PR review. -## Step 1: Survey current state +## Step 1: Inspect Current State ```bash python3 ./.trellis/scripts/get_context.py --mode record +git status --porcelain ``` -This prints: +Read the current task's acceptance and verification evidence. Inspect the task-owned diff and actual commits. Leave unrelated tasks alone unless the user asked to clean them up; do not introduce an unsolicited archive-confirmation prompt. -- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round. -- **Git status** — quick visual on what's dirty. -- **Recent commits** — you'll need their hashes in Step 4 for `--commit`. +## Step 2: Finish the Deliverable -If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless. +- If implementation or required checks remain, execute the applicable workflow step directly, then return here. Do not send the user away to invoke another command. +- If task changes are uncommitted and commits are authorized, perform Phase 3.4 directly. Otherwise retain the verified local diff and report commit status separately. An unrequested commit is not a local-delivery gate. +- Preserve unrelated dirty paths. Inspect mixed files/hunks before classifying ownership; stage only attributable task changes. Ask only if essential ownership cannot be established and the requested next action would affect unknown work. +- A requested PR/merge/release must satisfy its own authorization and latest-commit review requirements. Pending external work does not erase completed local work, but remains incomplete when included in the requested outcome. -## Step 2: Sanity check — classify dirty paths +## Step 3: Archive Only Completed Tasks -Run: +Archive a task only when its own acceptance is met, including merge/release if that task requires them. Archive only the current task or others explicitly included in the requested cleanup. Never archive an unfinished task to clear the active pointer. ```bash -git status --porcelain +python3 ./.trellis/scripts/task.py archive --help ``` -Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work. - -For each remaining dirty path, decide whether it belongs to **the current task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics: - -- Paths referenced in the current task's `prd.md` / `implement.jsonl` / `check.jsonl` → current task -- Paths in code areas matching the task's stated scope, or that you remember editing this session → current task -- Paths in unrelated areas you have no recollection of touching this session → other parallel work - -Then route: - -- **Any remaining path looks like current-task work** — bail out with: - > "Working tree has uncommitted code changes from this task: ``. Return to workflow Phase 3.4 to commit them before running `/trellis:finish-work`." - - Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there. -- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3: - > "FYI, dirty files outside this task's scope — leaving them for the other window: ``." -- **Genuinely unsure** — ask the user once: "Are `` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer. - -## Step 3: Archive task(s) +Inspect script/configuration side effects first. Archive can auto-commit: use a supported no-commit option when requested/needed, or leave the task unarchived if the operation cannot honor current constraints. Run permitted archive operations on a task branch only: ```bash python3 ./.trellis/scripts/task.py archive ``` -At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit. +If the user only asks to clear active state, `task.py finish` clears the session pointer without declaring completion. No active task means no archive step; do not manufacture one for this command. -If there is no active task and the user did not confirm any cleanup archives, skip this step. +## Step 4: Preserve Useful Context and Report -## Step 4: Record session journal +Record a journal only when it adds useful cross-session context and its side effects are authorized. Inspect `add_session.py --help` and auto-commit settings. Use actual task commit hashes; omit unsupported claims or fabricated hashes. Do not create commits merely to make a journal possible. ```bash -python3 ./.trellis/scripts/add_session.py \ - --title "Session Title" \ - --commit "hash1,hash2" \ - --summary "Brief summary" +python3 ./.trellis/scripts/add_session.py --title "Session Title" --commit "" --summary "Useful decisions and verified outcome" ``` -Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit. - -Final git log order: `` → `chore(task): archive ...` (one or more) → `chore: record journal`. +Remove only this session's disposable temporary files. Report what was delivered, the meaningful verification, and any requested step still blocked. Distinguish local delivery, commits, PR review, merge, deployment, and task archive where relevant. Finish authorized actions yourself rather than ending with a reminder for the user to run this command. diff --git a/.claude/hooks/inject-subagent-context.py b/.claude/hooks/inject-subagent-context.py index 975babc..fb79ba8 100644 --- a/.claude/hooks/inject-subagent-context.py +++ b/.claude/hooks/inject-subagent-context.py @@ -408,13 +408,14 @@ def build_check_prompt(original_prompt: str, context: str) -> str: 1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes 2. **Check against specs** - Check item by item against specs above -3. **Self-fix** - Fix issues directly, don't just report -4. **Run verification** - Run project's lint and typecheck commands +3. **Self-fix** - Fix task-related issues only when authorized; read-only review returns findings without edits +4. **Run verification** - Run checks applicable to changed behavior and relevant contracts; prose-only work needs consistency/parser checks ## Important Constraints -- Fix issues yourself, don't just report -- Must execute complete checklist in check specs +- Respect the dispatch write scope and preserve unrelated changes +- Apply relevant checklist items; do not manufacture inapplicable tests or documents +- Reuse valid checks on unchanged state; distinguish task regressions from unrelated or environment failures - Pay special attention to impact radius analysis (L1-L5)""" @@ -445,14 +446,14 @@ def build_finish_prompt(original_prompt: str, context: str) -> str: 2. **Verify task artifacts** - Check requirements in prd.md and, when present, design.md / implement.md 3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions - If new pattern/convention found: read target spec file → update it → update index.md if needed - - If infra/cross-layer change: follow the 7-section mandatory template from update-spec.md + - If infra/cross-layer change: document the affected contracts using only applicable update-spec sections - If pure code fix with no new patterns: skip this step -4. **Run final checks** - Execute lint and typecheck +4. **Run final checks** - Run proportionate checks for the affected behavior, reusing valid results on unchanged state 5. **Confirm ready** - Ensure code is ready for PR ## Important Constraints -- You MAY update spec files when gaps are detected (use update-spec.md as guide) +- You MAY update relevant spec files when gaps are detected and edits are authorized; read-only reviews only report findings - MUST read the target spec file BEFORE editing (avoid duplicating existing content) - Do NOT update specs for trivial changes (typos, formatting, obvious fixes) - If critical CODE issues found, report them clearly (fix specs, not code) diff --git a/.claude/hooks/session-start.py b/.claude/hooks/session-start.py index a7f28bf..67c6328 100644 --- a/.claude/hooks/session-start.py +++ b/.claude/hooks/session-start.py @@ -96,30 +96,6 @@ def _normalize_windows_shell_path(path_str: str) -> str: -def _has_curated_jsonl_entry(jsonl_path: Path) -> bool: - """Return True iff jsonl has at least one row with a ``file`` field. - - A freshly seeded jsonl only contains a ``{"_example": ...}`` row (no - ``file`` key) — that is NOT "ready". Readiness requires at least one - curated entry. Matches the contract used by hook-inject and pull-based - sub-agent context loaders. - """ - try: - for line in jsonl_path.read_text(encoding="utf-8").splitlines(): - line = line.strip() - if not line: - continue - try: - row = json.loads(line) - except json.JSONDecodeError: - continue - if isinstance(row, dict) and row.get("file"): - return True - except (OSError, UnicodeDecodeError): - return False - return False - - def should_skip_injection() -> bool: """Check if any platform's non-interactive flag is set, or if Trellis hooks are explicitly disabled via TRELLIS_HOOKS=0 / TRELLIS_DISABLE_HOOKS=1. @@ -331,9 +307,9 @@ def _get_task_status(trellis_dir: Path, input_data: dict) -> str: if not active.task_path: return ( "Status: NO ACTIVE TASK\n" - "Next-Action: Classify the current turn before creating any Trellis task. " - "Simple conversation / small task asks only whether this turn should create a Trellis task. " - "Complex task asks whether task creation and planning are allowed." + "Next-Action: Follow workflow.md request triage within existing authorization. " + "Simple answers and narrow rule maintenance may run inline. For product work, " + "check the branch before creating task files, then plan and implement as requested." ) task_ref = active.task_path @@ -342,7 +318,7 @@ def _get_task_status(trellis_dir: Path, input_data: dict) -> str: return ( f"Status: STALE POINTER\nTask: {task_ref}\n" f"Next-Action: Run `python3 ./.trellis/scripts/task.py finish` to clear the stale pointer, " - "then ask the user what to work on next." + "then continue the current request if its goal is known; clarify only an unresolved goal." ) task_json_path = task_dir / "task.json" @@ -365,48 +341,28 @@ def _get_task_status(trellis_dir: Path, input_data: dict) -> str: return ( f"Status: COMPLETED\nTask: {task_title}\n" f"Present: {present_line}\n" - "Next-Action: Run `/trellis:finish-work`. If the working tree is dirty, return to Phase 3.4 first." + "Next-Action: Verify acceptance and execute authorized finish-work steps. " + "Preserve unrelated dirty files; do not require an unrequested commit or archive unfinished work." ) has_prd = (task_dir / "prd.md").is_file() - has_design = (task_dir / "design.md").is_file() - has_implement_plan = (task_dir / "implement.md").is_file() - implement_jsonl = task_dir / "implement.jsonl" - check_jsonl = task_dir / "check.jsonl" - jsonl_ready = ( - (not implement_jsonl.is_file() or _has_curated_jsonl_entry(implement_jsonl)) - and (not check_jsonl.is_file() or _has_curated_jsonl_entry(check_jsonl)) - ) if task_status == "planning" and not has_prd: return ( f"Status: PLANNING\nTask: {task_title}\n" f"Present: {present_line}\n" - "Next-Action: Load `trellis-brainstorm` and write `prd.md`. Stay in planning." + "Next-Action: Establish scope and acceptance in `prd.md`; use trellis-brainstorm " + "only for material ambiguity. Then follow workflow.md readiness and existing authorization." ) if task_status == "planning": - missing_complex = [ - name for name, exists in ( - ("design.md", has_design), - ("implement.md", has_implement_plan), - ) - if not exists - ] - next_bits: list[str] = [] - if missing_complex: - next_bits.append( - "Lightweight task can request start review with PRD-only; " - f"complex task must add {', '.join(missing_complex)} before start" - ) - else: - next_bits.append("Planning artifacts are present; ask for review before `task.py start`") - if not jsonl_ready: - next_bits.append("curate `implement.jsonl` and `check.jsonl` before sub-agent mode start") return ( f"Status: PLANNING\nTask: {task_title}\n" f"Present: {present_line}\n" - f"Next-Action: {'; '.join(next_bits)}. Do not enter implementation until the user confirms start." + "Next-Action: Check scope and acceptance against workflow.md. When implementation " + "is authorized and no material blocker remains, run `task.py start` and continue " + "without another approval. Extra documents and curated JSONL are needed only for " + "a concrete purpose; planning-only requests end with the plan." ) return ( diff --git a/.claude/skills/trellis-before-dev/SKILL.md b/.claude/skills/trellis-before-dev/SKILL.md index 5a4b852..183ba97 100644 --- a/.claude/skills/trellis-before-dev/SKILL.md +++ b/.claude/skills/trellis-before-dev/SKILL.md @@ -7,7 +7,7 @@ Read the relevant development guidelines before starting your task. Execute these steps: -1. **Read current task artifacts**: +1. **Read current task artifacts when present** (taskless work uses its requested scope and inline acceptance plan): - `prd.md` for requirements and acceptance criteria - `design.md` if present for technical design - `implement.md` if present for execution order and validation plan @@ -30,7 +30,7 @@ Execute these steps: 5. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns. -6. **Always read shared guides**: +6. **Read shared guides when relevant** to reuse, cross-layer changes, or another concrete uncertainty; skip already loaded, unchanged guidance: ```bash cat .trellis/spec/guides/index.md ``` diff --git a/.claude/skills/trellis-brainstorm/SKILL.md b/.claude/skills/trellis-brainstorm/SKILL.md index 806ee31..3a8e769 100644 --- a/.claude/skills/trellis-brainstorm/SKILL.md +++ b/.claude/skills/trellis-brainstorm/SKILL.md @@ -1,15 +1,15 @@ --- name: trellis-brainstorm -description: "Guides collaborative requirements discovery before implementation. Creates task directory, seeds PRD, asks high-value questions one at a time, researches technical choices, and converges on MVP scope. Use when requirements are unclear, there are multiple valid approaches, or the user describes a new feature or complex task." +description: "Resolves consequential requirement ambiguity using existing evidence and focused questions. Use when missing user intent materially changes the goal or acceptance; complexity or multiple routine implementation choices alone do not trigger an interview." --- # Trellis Brainstorm -## Non-Negotiable Interview Contract +## Clarification Boundary -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. +Ask only when unresolved intent materially changes the goal, correctness, or consequences. Choose reasonable reversible implementation details from repository patterns. A user explicitly requesting an exhaustive interview may expand this scope. -Ask the questions one at a time. +Ask the smallest useful set of related questions, with a recommendation where justified. Stop questioning once there is enough information to execute; continue independent authorized work while awaiting answers. ## Non-Negotiable Evidence Rule @@ -25,9 +25,9 @@ Use this skill during Phase 1 planning to turn the user's request into clear req ## Preconditions -Use this skill only after task-creation consent has been given and the user is ready to enter Trellis planning. +Follow `.trellis/workflow.md` for task selection. An implementation request authorizes necessary local planning and task creation; do not request separate process consent. Planning-only requests remain planning-only. -If no task exists yet, create one: +If the work needs durable task tracking and no matching task exists, create one; otherwise use a concise inline plan: ```bash TASK_DIR=$(python3 ./.trellis/scripts/task.py create "" --slug ) @@ -49,19 +49,19 @@ Use a concise title from the user's request. Use a slug without a date prefix. ` - product intent still needed from the user - scope or risk decisions still needed from the user - likely out-of-scope items -4. Ask the single highest-value remaining question. -5. Include your recommended answer with the question. +4. Resolve reversible details directly; ask only consequential unresolved questions. +5. Include a recommendation when the evidence supports one. 6. After each user answer, update `prd.md` before continuing. -7. For complex tasks, create or update `design.md` and `implement.md` before implementation starts. +7. Add `design.md` or `implement.md` only if each has a useful separate purpose for decisions, coordination, or resumption. 8. Before final review or `task.py start`, run the PRD convergence pass below. Do not invent a project-specific product/spec hierarchy. If the repository already has product, domain, or spec docs, use them. If it does not, proceed with the evidence that exists. ## Question Rules -Ask only one question per message. +Keep questions concise; batch closely related missing inputs when it reduces back-and-forth. Do not ask facts already established in the conversation or repository. -Each question must include: +For each consequential question, make clear: - the decision needed - why the answer matters @@ -139,13 +139,13 @@ For each component of the current plan: - risky files or rollback points - follow-up checks before `task.py start` -Lightweight tasks may have only `prd.md`. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`. +`prd.md` can be sufficient regardless of size when it captures the goal and acceptance. Additional documents are useful for independently meaningful design/coordination needs, not a complexity gate. Taskless work uses an inline plan. -`implement.md` is not a replacement for `implement.jsonl`. On sub-agent-dispatch workflows, `implement.jsonl` and `check.jsonl` must each contain at least one real spec/research entry before `task.py start`; the seed `_example` row does not count. Inline workflows skip this JSONL gate because Phase 2 loads context through `trellis-before-dev`. +`implement.jsonl` and `check.jsonl` list relevant context for actual dispatched agents. Curate only manifests that will be consumed; inline execution loads context directly through `trellis-before-dev`. The seed `_example` row is not usable context. ## PRD Convergence Pass -Before declaring planning ready or running `task.py start`, rewrite `prd.md` once against the final structure described in the artifact rules above. This is not optional cleanup; it is the final planning gate. +Before proceeding, check that the PRD or inline plan accurately captures scope and acceptance. Edit inconsistencies or duplication when needed; do not rewrite an already sufficient plan as a mandatory gate. The pass must be lossless: @@ -153,7 +153,7 @@ The pass must be lossless: - Fold temporary brainstorm sections such as `What I already know`, `Assumptions`, and resolved `Open Questions` into Goal, Background, Requirements, Technical Notes, or Acceptance Criteria. - Remove resolved open questions instead of leaving empty or already-answered sections. - Merge parallel bug and requirement lists when they describe the same work; keep each defect's severity, evidence, and file:line anchors on the owning requirement. -- Preserve every file:line anchor, decision, constraint, requirement ID, and acceptance-criteria mapping. +- Preserve useful evidence, decisions, constraints, requirement IDs, and acceptance mappings; discard obsolete investigation details. - Keep only genuinely blocking open questions. After the pass, read `prd.md` top to bottom and verify that no fact is repeated across sections unless the repetition adds new information. @@ -163,11 +163,10 @@ After the pass, read `prd.md` top to bottom and verify that no fact is repeated Before declaring planning ready: - `prd.md` contains testable acceptance criteria. -- `prd.md` has passed the PRD convergence pass: no unresolved temporary brainstorm sections, no duplicate facts across sections, and no lost anchors, decisions, or acceptance mappings. +- The PRD or inline plan has enough consistent scope and acceptance to guide execution. - Repository-answerable questions have already been answered through inspection. - Remaining open questions are genuinely about user intent or scope. -- Complex tasks have `design.md` and `implement.md`. -- Sub-agent-dispatch tasks have real curated entries in both `implement.jsonl` and `check.jsonl`; seed-only manifests are not ready. -- The user has reviewed the final planning artifacts or explicitly approved proceeding. +- Additional documents or manifests exist only where execution actually needs them. +- The requested next action is covered by existing authorization. -Do not start implementation until the user approves or asks for implementation. +When implementation was already requested, activate any applicable task and proceed without another approval. When the user asked only for discovery/planning, deliver the plan. A remaining consequential blocker pauses only dependent work. diff --git a/.claude/skills/trellis-break-loop/SKILL.md b/.claude/skills/trellis-break-loop/SKILL.md index 1c8b397..28b4b03 100644 --- a/.claude/skills/trellis-break-loop/SKILL.md +++ b/.claude/skills/trellis-break-loop/SKILL.md @@ -125,7 +125,7 @@ Before investigating, state what you believe and why: | H2: [cause B] | 30% | Plausible given environment | | H3: [other] | 30% | Catch-all | -Priors must sum to 100%. If you can't assign probabilities, investigate first. +Use qualitative confidence when numerical priors are unsupported. Investigate the evidence that best separates plausible causes; do not manufacture probabilities as a gate to action. ### Step 2: Observe Evidence @@ -173,16 +173,17 @@ Never express binary certainty when evidence is incomplete. Use "most likely", " ## After Analysis: Immediate Actions -**IMPORTANT**: After completing the analysis above, you MUST immediately: +After analysis, finish the authorized debugging outcome and preserve only useful new knowledge: -1. **Update spec/guides** - Don't just list TODOs, actually update the relevant files: +1. **Fix and verify** the task's root cause when implementation is requested. An analysis-only request ends with evidence and a concrete recommendation. +2. **Update an owning spec/guide only when needed** for a changed contract or reusable non-obvious lesson. Confirm the target exists and fits this repository: - If it's a cross-platform issue → update `cross-platform-thinking-guide.md` - If it's a cross-layer issue → update `cross-layer-thinking-guide.md` - If it's a code reuse issue → update `code-reuse-thinking-guide.md` - If it's domain-specific → update `backend/*.md` or `frontend/*.md` -2. **Sync templates** - After updating `.trellis/spec/`, sync to `src/templates/markdown/spec/` +3. **Sync templates only when applicable**: do so only if this repository owns a corresponding template and the task requires both. Do not assume upstream Trellis template paths exist in an application repository. -3. **Commit the spec updates** - This is the primary output, not just the analysis text +4. **Follow existing commit authorization** in workflow Phase 3.4. Documentation and commits are not unconditional completion gates. -> **The analysis is worthless if it stays in chat. The value is in the updated specs.** +If the same failure repeats, change the hypothesis or diagnostic method. Complete independent work and report the exact missing input/access if further progress is externally blocked. diff --git a/.claude/skills/trellis-channel/SKILL.md b/.claude/skills/trellis-channel/SKILL.md index 511ee02..d5ec64c 100644 --- a/.claude/skills/trellis-channel/SKILL.md +++ b/.claude/skills/trellis-channel/SKILL.md @@ -47,7 +47,7 @@ trellis channel context list --scope global --thread - Pretty `messages` output is an operator dashboard and may truncate progress. Use `--raw` for audit. - `--as` is the speaker or worker handle, depending on the command. Use explicit, stable names when multiple agents or sessions are involved. - `--scope project` (default) operates on the current cwd's project bucket; `--scope global` operates on the shared `__global__` bucket. Pick scope deliberately — a global board is invisible from project listings unless `--scope global` is passed. -- For brainstorm, do multiple pressure-test rounds. One answer plus one confirmation is review, not brainstorm. +- For brainstorm, test assumptions until the material uncertainty is resolved. Do not require a fixed number of rounds or extra confirmations once scope and acceptance are sufficient. - **Dispatcher wait pattern**: use `--kind done` / `--kind turn_finished` (trellis-emitted system events), NOT a user `--tag` as the completion signal. CLI help lists `phase_done` / `question` as `--tag` examples but only `interrupt` is a reserved tag with hardcoded trellis behavior; the others are opaque user labels. Relying on a worker to run `send --tag ` is unreliable — LLM workers commonly write the tag string into prose instead of running the actual CLI command. See `references/command-reference.md` "tag vs kind". - Forum channels are event-sourced. Do not parse `events.jsonl` first; use `forum`, `thread`, `messages --thread`, and `context list`. - `@mindfoldhq/trellis-core` owns reusable channel/thread state, event append, seq allocation, context/title projection, reducers, and task helpers. The CLI owns flags, terminal rendering, prompts, worker lifecycle, and process exits. diff --git a/.claude/skills/trellis-channel/references/workflows.md b/.claude/skills/trellis-channel/references/workflows.md index 3319764..073acd9 100644 --- a/.claude/skills/trellis-channel/references/workflows.md +++ b/.claude/skills/trellis-channel/references/workflows.md @@ -25,10 +25,10 @@ trellis channel wait brainstorm-storage-layer \ --as main --kind done --from cx-arch --timeout 10m ``` -Do not stop after one answer. Read the answer, identify vague areas, send a -new probe, and repeat until the result is executable. +Read the answer against the requested decision. Send another probe only when +material uncertainty remains; stop once evidence supports an executable result. -Minimum round structure: +Possible topics, only where relevant: 1. Direction split: should this live in an existing mechanism or a new one? 2. MVP boundary: v1, v2, and what would force v2 back into v1. @@ -42,9 +42,9 @@ Optional rounds: - Migration/release: breaking status, manifest, changelog, docs-site. - Opposition review: ask the peer agent to argue against the current plan. -Every probe should request concrete file paths, commands, schema, rejected -alternatives, and release-blocking issues. Reject hedging when a decision is -needed. +Ask for the evidence needed by that particular decision. Do not require every +probe to cover paths, commands, schema, alternatives, and release concerns. +Distinguish supported conclusions from uncertainty instead of forcing confidence. ## Pattern B: Implement / Check Agent diff --git a/.claude/skills/trellis-check/SKILL.md b/.claude/skills/trellis-check/SKILL.md index c695abd..ba4470b 100644 --- a/.claude/skills/trellis-check/SKILL.md +++ b/.claude/skills/trellis-check/SKILL.md @@ -1,11 +1,13 @@ --- name: trellis-check -description: "Comprehensive quality verification: spec compliance, lint, type-check, tests, cross-layer data flow, code reuse, and consistency checks. Use when code is written and needs quality verification, before committing changes, or to catch context drift during long sessions." +description: "Verify changed behavior against acceptance and relevant contracts with checks proportionate to risk. Use after implementation or meaningful changes, before delivery or authorized commits." --- # Code Quality Check -Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks. +Verify the entire current task diff against acceptance and applicable specs. Preserve unrelated work and distinguish regressions from pre-existing failures or environment limits. + +When the request is a read-only review, return findings without edits. The fix steps below apply only when implementing or correcting the changes is authorized. --- @@ -38,7 +40,7 @@ Read the specific guideline files referenced — the index is a pointer, not the ## Step 3: Run Project Checks -Run the project's lint, type-check, and test commands. Fix any failures before proceeding. +Run required repository checks applicable to affected layers, plus meaningful tests scaled to risk and blast radius. Prose/rule changes generally need consistency, links, and any relevant parser checks, not the full application suite. Fix this task's regressions or issues necessary for its outcome; report unrelated failures and environment limits without widening scope. ## Step 4: Review Against Checklist @@ -52,9 +54,9 @@ Run the project's lint, type-check, and test commands. Fix any failures before p ### Test Coverage -- [ ] New function → unit test added? -- [ ] Bug fix → regression test added? -- [ ] Changed behavior → existing tests updated? +- [ ] Important new behavior or regression risk has meaningful coverage? +- [ ] Existing tests reflect changed contracts where needed? +- [ ] Reversible low-impact changes avoid tests that merely restate the implementation? ### Spec Sync @@ -77,9 +79,9 @@ Skip this step if your change is confined to a single layer. - [ ] Searched for existing similar code before creating new? ```bash - grep -r "pattern" src/ + rg "pattern" src/ ``` -- [ ] If 2+ places define same value → extracted to shared constant? +- [ ] Shared abstractions remove real complexity or meaningful duplication without coupling unrelated concepts? - [ ] After batch modification, all occurrences updated? ### C. Import/Dependency (creating new files) @@ -95,4 +97,4 @@ Skip this step if your change is confined to a single layer. ## Step 6: Report and Fix -Report violations found and fix them directly. Re-run project checks after fixes. +Fix findings introduced by this task or needed for its acceptance, then rerun affected checks. Once applicable checks pass, proceed to completion. Broaden/repeat only for new edits, failures, or unresolved concerns. Report persistent blockers precisely; do not loop indefinitely or silently expand into unrelated cleanup. diff --git a/.claude/skills/trellis-meta/references/customize-local/change-agents.md b/.claude/skills/trellis-meta/references/customize-local/change-agents.md index 88e7376..319092b 100644 --- a/.claude/skills/trellis-meta/references/customize-local/change-agents.md +++ b/.claude/skills/trellis-meta/references/customize-local/change-agents.md @@ -6,8 +6,8 @@ When the user wants to change `trellis-research`, `trellis-implement`, or `trell 1. Target platform agent directory 2. `.trellis/workflow.md` Phase 2 / research routing -3. Current task `prd.md` -4. Current task `implement.jsonl` / `check.jsonl` +3. Current task `prd.md` when present, otherwise the dispatch scope +4. Existing relevant `implement.jsonl` / `check.jsonl` entries when used 5. Relevant hook or agent prelude ## Common Paths @@ -41,15 +41,15 @@ Use the actual paths in the user project as authoritative. ## Modification Principles -1. **Preserve role boundaries**: research investigates and persists; implement writes implementation; check reviews and fixes. +1. **Preserve role boundaries**: research returns evidence and persists only when durable output is requested or useful; implement writes implementation; check reviews and fixes only when authorized. 2. **Do not hard-code project specs into agents**: long-term specs belong in `.trellis/spec/`; agents are responsible for reading them. -3. **Make read order explicit**: active task -> PRD -> info -> JSONL -> spec/research. +3. **Make read order explicit**: dispatch scope and task path when present, then relevant existing task artifacts and spec/research. Taskless assignments do not require manufacturing a task. 4. **Make write boundaries explicit**: which directories may be written and which may not. 5. **Synchronize across platforms**: when the user configured multiple platforms, decide whether to change only the current platform or all platform agents. ## Agent Pull Platforms -If an agent file contains a prelude for "read task/context after startup," do not remove those steps when editing. Otherwise the agent will work only from chat context and bypass Trellis's core mechanism. +Preserve relevant context loading in the prelude. Reuse supplied context and make task artifacts conditional on their existence and purpose; taskless work still reads applicable specs. ## Hook Push Platforms diff --git a/.claude/skills/trellis-meta/references/customize-local/change-workflow.md b/.claude/skills/trellis-meta/references/customize-local/change-workflow.md index 337c985..dd0daa4 100644 --- a/.claude/skills/trellis-meta/references/customize-local/change-workflow.md +++ b/.claude/skills/trellis-meta/references/customize-local/change-workflow.md @@ -17,14 +17,14 @@ When the user wants to change Trellis phases, next-action hints, whether to crea | Change the next step during planning | Phase 1 and `[workflow-state:planning]`. | | Change whether an agent is required during in_progress | Phase 2 and `[workflow-state:in_progress]`. | | Change wrap-up after completion | Phase 3 and `[workflow-state:completed]`. | -| Change which skill a user intent triggers | `Skill Routing` table. | +| Change which skill a user intent triggers | Request Triage, Routing and Completion Rules, and the relevant numbered phase step. | ## Modification Steps 1. Find the relevant section in `.trellis/workflow.md`. 2. When changing rules, keep explicit trigger conditions and next actions. 3. If adding or renaming a skill/agent, synchronize the corresponding files in platform directories. -4. Workflow-state changes only need an edit to the `[workflow-state:STATUS]` block in `.trellis/workflow.md`. The hook is parser-only — it reads whatever you put in the block. Keep the opening and closing tags' STATUS strings identical (`[workflow-state:foo]…[/workflow-state:foo]`); mismatched STATUS pairs are silently dropped. +4. The per-turn workflow-state hook parses `[workflow-state:STATUS]` blocks from `.trellis/workflow.md`; keep paired STATUS strings identical. Also inspect `.claude/hooks/session-start.py`, which emits its own task next-action hints, and the continue command. Keep all actual entry points consistent with the changed policy. 5. Make the AI reread `.trellis/workflow.md`; do not keep using rules from the old conversation. ## Example: Relax Task Creation Requirements @@ -33,7 +33,7 @@ To change when task creation can be skipped, usually edit `[workflow-state:no_ta ```md [workflow-state:no_task] -Task is not required when the answer is a one-reply explanation, no files are changed, and no research is needed. +Simple answers, read-only audits, and narrow documentation/rule maintenance may run without a task. For product work, reuse/create useful local tracking within existing authorization; do not ask for process consent. [/workflow-state:no_task] ``` @@ -41,7 +41,7 @@ If the formal Phase 1 flow also needs to change, synchronize the Phase 1 section ## Example: One Platform Does Not Use Sub-Agents -If the user wants only one platform to avoid sub-agents, first confirm whether that platform has a separate group in the workflow. Then change Phase 2 routing for that platform group instead of deleting all `trellis-implement` / `trellis-check` instructions across platforms. +Direct execution is already the default on every platform. If the user wants a stricter platform-specific delegation rule, add that scoped exception to Phase 2 and its applicable state block; inspect existing routing rather than assuming a platform group exists. Preserve usable optional agent definitions for other workflows. ## `/trellis:continue` Route Table @@ -50,10 +50,10 @@ If the user wants only one platform to avoid sub-agents, first confirm whether t | `status` | Artifact state | Resume at | | --- | --- | --- | | `planning` | `prd.md` missing | Phase 1.1 (load `trellis-brainstorm`) | -| `planning` | lightweight task with `prd.md` complete | ask for start review, then run `task.py start` | -| `planning` | complex task missing `design.md` or `implement.md` | complete missing planning artifacts | -| `planning` | complex task has `prd.md`, `design.md`, and `implement.md` | ask for start review, then run `task.py start` | -| `in_progress` | no implementation in conversation history | Phase 2.1 (`trellis-implement`) | +| `planning` | sufficient scope/acceptance and implementation authorized | run `task.py start` and continue without another approval | +| `planning` | consequential decision or necessary context missing | inspect evidence, complete useful context, clarify only a material blocker | +| `planning` | extra documents absent but scope/acceptance sufficient | proceed; complexity alone does not require design/implementation documents | +| `in_progress` | implementation unfinished | Phase 2.1 (direct implementation; optional useful delegation) | | `in_progress` | implementation done, no `trellis-check` run | Phase 2.2 (`trellis-check`) | | `in_progress` | check passed | Phase 3.3 (spec update) → 3.4 (commit) | | `completed` | task is still in active tree | Phase 3.5 (run `/trellis:finish-work` to archive) | diff --git a/.claude/skills/trellis-meta/references/local-architecture/workflow.md b/.claude/skills/trellis-meta/references/local-architecture/workflow.md index f0659ff..d1e409b 100644 --- a/.claude/skills/trellis-meta/references/local-architecture/workflow.md +++ b/.claude/skills/trellis-meta/references/local-architecture/workflow.md @@ -22,10 +22,7 @@ Each phase contains numbered steps, such as `1.3 Configure context`. These numbe ## Skill Routing -`workflow.md` separates routing by platform capability: - -- Platforms with sub-agent support: dispatch `trellis-implement` by default for implementation and `trellis-check` for checking. -- Platforms without sub-agent support: the main session reads skills such as `trellis-before-dev`, then executes directly. +`workflow.md` describes routing in Request Triage, Routing and Completion Rules, and Phase 2. Direct execution is the default. Delegate only an independent bounded task when permitted and useful; platform capability alone does not require delegation. The main session reads applicable skills and can implement/check inline when agent tooling is unavailable. When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync. @@ -48,7 +45,7 @@ Hooks choose the right block based on current task status and inject it into the | `in_progress` | The task has entered implementation and checking. | | `completed` | The task is complete and waiting for wrap-up or archive. | -If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them. +To change task creation or delegation policy, edit these state blocks and the matching Request Triage, Routing and Completion Rules, and numbered phase steps. Also inspect SessionStart hints for duplicated policy. ## Local Modification Patterns @@ -59,8 +56,8 @@ Common changes: | Add a phase | Update the Phase Index, phase body, routing, and state blocks. | | Change task creation policy | Update the `no_task` state block and Phase 1 description. | | Change the default implementation/check path | Update Phase 2 and skill routing. | -| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. | -| Change platform differences | Update routing descriptions grouped by platform. | +| Change the wrap-up flow | Update Phase 3 and `finish-work` together. Phase 3.4 executes commits within existing authorization; Phase 3.5 completes applicable wrap-up. Preserve unrelated dirty paths, archive only accepted tasks, and distinguish local delivery from commit/release state. | +| Change platform differences | Add a scoped exception to the relevant phase and state block only when that platform needs one. | After editing, make the AI reread `.trellis/workflow.md`; do not assume the flow from the old conversation is still valid. diff --git a/.claude/skills/trellis-meta/references/platform-files/agents.md b/.claude/skills/trellis-meta/references/platform-files/agents.md index a07cae7..fff44b1 100644 --- a/.claude/skills/trellis-meta/references/platform-files/agents.md +++ b/.claude/skills/trellis-meta/references/platform-files/agents.md @@ -12,9 +12,9 @@ File locations and formats differ by platform, but responsibility boundaries sho | Agent | Responsibility | | --- | --- | -| `trellis-research` | Investigate the question and write findings into the current task's `research/`. | +| `trellis-research` | Return findings and evidence; persist under the task's `research/` only when durable output is requested or useful. A taskless read-only lookup may return directly. | | `trellis-implement` | Implement against `prd.md`, optional `design.md` / `implement.md`, `implement.jsonl`, and related spec/research. | -| `trellis-check` | Review changes, fix discovered issues, and run necessary checks. | +| `trellis-check` | Review changes and run necessary checks; fix task-related issues only when authorized, preserving a read-only review boundary. | Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported. @@ -49,7 +49,7 @@ Common on platforms that support agent hooks. ### agent pull -The agent file instructs the agent to read after startup: +The agent file instructs the agent to use the dispatch scope and supplied task path first, then read relevant existing artifacts after startup: - `python3 ./.trellis/scripts/task.py current --source` - `implement.jsonl` or `check.jsonl` @@ -60,6 +60,8 @@ The agent file instructs the agent to read after startup: This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts. +For taskless assignments, read the brief and relevant specs directly. Missing optional task artifacts do not require creating files or interrupting the user. + ## Local Change Scenarios | User need | Edit location | @@ -73,8 +75,8 @@ This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts. ## Modification Principles 1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent. -2. **Specify the read order**. Agents must know to start from the active task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present. -3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues. +2. **Specify the read order**. Start from dispatch scope and the supplied task path when present, then relevant existing manifests/specs and task artifacts. Taskless work uses the brief and applicable specs. +3. **Specify write boundaries**. Research writes only its authorized output when persistence is needed; implement writes assigned code; check fixes only when authorized. 4. **Keep semantics synchronized in multi-platform projects**. If the user configured Claude, Codex, and Cursor together, decide whether changes to one platform's agent also need to be applied to others. ## Do Not Default To Editing Upstream Templates diff --git a/.claude/skills/trellis-update-spec/SKILL.md b/.claude/skills/trellis-update-spec/SKILL.md index 557bc4e..e85e04b 100644 --- a/.claude/skills/trellis-update-spec/SKILL.md +++ b/.claude/skills/trellis-update-spec/SKILL.md @@ -18,26 +18,26 @@ In this project, "spec" for implementation work means **code-spec**: - Concrete signatures, payload fields, env keys, and boundary behavior - Testable validation/error behavior -If the change touches infra or cross-layer contracts, code-spec depth is mandatory. +When infrastructure or cross-layer behavior changes a durable contract, update its owning spec with the concrete details needed by future implementers. -### Mandatory Triggers +### Contract Review Triggers -Apply code-spec depth when the change includes any of: +Review the owning spec when the change includes any of: - New/changed command or API signature - Cross-layer request/response contract change - Database schema/migration change - Infra integration (storage, queue, cache, secrets, env wiring) -### Mandatory Output (7 Sections) +### Useful Content -For triggered tasks, include all sections below: +Include only the applicable details below, preferably in existing sections. Do not add empty sections, duplicate code/tests, or require a seven-section rewrite for a small contract change: 1. Scope / Trigger 2. Signatures (command/API/DB) 3. Contracts (request/response/env) 4. Validation & Error Matrix 5. Good/Base/Bad Cases 6. Tests Required (with assertion points) -7. Wrong vs Correct (at least one pair) +7. Wrong vs Correct (only for a non-obvious recurring pitfall) --- @@ -53,7 +53,7 @@ For triggered tasks, include all sections below: | **Established a convention** | Team agreed on naming pattern | Quality guidelines | | **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item) | -**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely. +Update specs for changed contracts or reusable knowledge absent from current guidance. A routine feature/fix that adds no such information needs no documentation write. --- @@ -143,7 +143,9 @@ If you added a new section or the code-spec status changed, update the category' ## Update Templates -### Mandatory Template for Infra/Cross-Layer Work +### Optional Template for Infra/Cross-Layer Work + +Use only sections needed to explain the changed contract; a small edit to the owning spec is often sufficient. ```markdown ## Scenario: @@ -315,15 +317,14 @@ If you're unsure what to update, answer these prompts: ## Quality Checklist -Before finishing your code-spec update: +Before finishing, check applicable items only. Omit examples, signatures, matrices, case sets, or tests that do not clarify this change; missing inapplicable sections are not a completion failure. - [ ] Is the content specific and actionable? -- [ ] Did you include a code example? +- [ ] Is a code example included when needed to explain non-obvious behavior? - [ ] Did you explain WHY, not just WHAT? -- [ ] Did you include executable signatures/contracts? -- [ ] Did you include validation and error matrix? -- [ ] Did you include Good/Base/Bad cases? -- [ ] Did you include required tests with assertion points? +- [ ] Are affected executable signatures/contracts recorded when relevant? +- [ ] Are changed validation/error behavior and useful case distinctions clear? +- [ ] Are meaningful required tests and assertions documented when the change needs them? - [ ] Is it in the right code-spec file? - [ ] Does it duplicate existing content? - [ ] Would a new team member understand it? diff --git a/.trellis/agents/check.md b/.trellis/agents/check.md index 6c1bf13..8184fa6 100644 --- a/.trellis/agents/check.md +++ b/.trellis/agents/check.md @@ -12,6 +12,8 @@ You are the Check Agent spawned by `trellis channel spawn --agent check` inside ## Context +For a taskless review, use the dispatch scope and relevant specs directly. The brief determines whether edits are authorized; an absent task directory does not block a read-only review. + Before reviewing, read in this order: 1. `/check.jsonl` if present — spec manifest curated for this turn; read every listed file @@ -25,8 +27,8 @@ Before reviewing, read in this order: 1. **Get the diff** — `git diff` / `git diff --staged` for uncommitted changes 2. **Review against task artifacts** — does the diff satisfy `prd.md` (and `design.md` / `implement.md` if present)? 3. **Review against specs** — naming, structure, type safety, error handling, conventions in `.trellis/spec/` -4. **Self-fix** — when an issue is mechanical and small, fix it directly with the editing tools you have -5. **Run verification** — project lint and typecheck on the changed scope +4. **Self-fix** — fix small task-related issues when authorized; read-only reviews report findings without edits +5. **Run verification** — checks appropriate to the changed scope and relevant contracts 6. **Report** — concrete findings with `file:line` citations and what was fixed vs. what is open ## Forbidden Operations @@ -42,9 +44,9 @@ The supervising main session owns commits. Report the post-fix state; do not com 1. Run `git diff --name-only` and `git diff` to scope the changes 2. Read the task artifacts and relevant spec files 3. For each issue: - - If mechanical (lint nit, missing type, wrong import, dead branch) → fix in-place + - If mechanical and fixes are authorized → fix in-place within the assigned scope - If a design/judgment issue → record and report, do not silently rewrite -4. Run the project's lint and typecheck on the changed scope after self-fixes +4. Run affected checks after self-fixes; prose-only changes need consistency/parser checks. Reuse valid results, and distinguish task regressions from unrelated or environment failures 5. Report ## Report Format diff --git a/.trellis/agents/implement.md b/.trellis/agents/implement.md index 3262f79..42195a5 100644 --- a/.trellis/agents/implement.md +++ b/.trellis/agents/implement.md @@ -12,6 +12,8 @@ You are the Implement Agent spawned by `trellis channel spawn --agent implement` ## Context +For an explicitly taskless assignment, use the dispatch scope and relevant specs directly. Do not manufacture task artifacts or ask the user for a routine output path. + Before implementing, read in this order: 1. `/implement.jsonl` if present — spec manifest curated for this turn; read every listed file @@ -25,7 +27,7 @@ Before implementing, read in this order: 1. **Understand specs** — read relevant spec files in `.trellis/spec/` 2. **Understand task artifacts** — read the artifacts listed above 3. **Implement features** — write code that follows specs and existing patterns -4. **Self-check** — run lint and typecheck on the changed scope before reporting +4. **Self-check** — run checks appropriate to the changed scope and relevant project contracts ## Forbidden Operations @@ -40,7 +42,7 @@ The supervising main session owns commits. Report what changed; do not commit on 1. Read relevant specs based on task type and the files in `implement.jsonl` if present 2. Read the task's `prd.md`, `design.md` if present, and `implement.md` if present 3. Implement features following specs and existing patterns -4. Run the project's lint and typecheck commands on the changed scope +4. Run applicable checks; use consistency/parser checks for prose and meaningful code checks for changed behavior 5. Report files touched, key decisions, and verification results back to the channel ## Code Standards @@ -48,7 +50,7 @@ The supervising main session owns commits. Report what changed; do not commit on - Follow existing code patterns - Don't add unnecessary abstractions - Only do what the PRD asks for; no speculative scope expansion -- Surface uncertainty back to the channel rather than guessing +- Resolve routine reversible choices from context; surface only consequential unresolved gaps to the supervising agent ## Report Format diff --git a/.trellis/scripts/common/task_store.py b/.trellis/scripts/common/task_store.py index bed8f34..9b4850b 100755 --- a/.trellis/scripts/common/task_store.py +++ b/.trellis/scripts/common/task_store.py @@ -184,8 +184,9 @@ def _default_prd_content(title: str, description: str | None = None) -> str: ## Notes - Keep `prd.md` focused on requirements, constraints, and acceptance criteria. -- Lightweight tasks can remain PRD-only. -- For complex tasks, add `design.md` for technical design and `implement.md` for execution planning before `task.py start`. +- A clear goal and acceptance criteria can be sufficient in `prd.md` alone. +- Add `design.md` or `implement.md` only for useful durable design or coordination; complexity alone does not require them. +- Follow workflow.md readiness and existing authorization before `task.py start`; do not request a second implementation approval. """ @@ -352,8 +353,9 @@ def cmd_create(args: argparse.Namespace) -> int: print("", file=sys.stderr) print(colored("Next steps:", Colors.BLUE), file=sys.stderr) print(" - Fill prd.md with requirements and acceptance criteria", file=sys.stderr) - print(" - Lightweight task: PRD-only is valid", file=sys.stderr) - print(" - Complex task: add design.md and implement.md before task.py start", file=sys.stderr) + print(" - PRD-only is valid when goal and acceptance are sufficient", file=sys.stderr) + print(" - Add design.md / implement.md only for useful design or coordination", file=sys.stderr) + print(" - Follow workflow.md readiness and existing authorization for task.py start", file=sys.stderr) if seeded_jsonl: print( " - Curate implement.jsonl / check.jsonl as spec/research manifests when sub-agents need context", diff --git a/.trellis/workflow.md b/.trellis/workflow.md index 5f70366..cd0dd97 100644 --- a/.trellis/workflow.md +++ b/.trellis/workflow.md @@ -1,708 +1,211 @@ # Development Workflow ---- - ## Core Principles -1. **Plan before code** — figure out what to do before you start -2. **Specs injected, not remembered** — guidelines are injected via hook/skill, not recalled from memory -3. **Persist everything** — research, decisions, and lessons all go to files; conversations get compacted, files don't -4. **Incremental development** — one task at a time -5. **Capture learnings** — after each task, review and write new knowledge back to spec - ---- +1. A request to implement, fix, or optimize authorizes necessary local investigation, planning, edits, and verification. Planning-only and review-only requests end at their requested deliverable. +2. Resolve facts from the conversation and relevant repository evidence before asking. Choose reasonable reversible details autonomously; clarify only when missing information materially changes the goal, correctness, or consequences. +3. Existing authorization carries through phases. Ask only for a concrete action outside it, after completing independent preparation. Waiting on one answer does not block other authorized work. +4. Scale planning, documentation, delegation, and testing to the work. Complexity alone does not require extra files, sub-agents, or an approval ceremony. +5. Finish the requested outcome with evidence and authorized wrap-up. Distinguish local completion from commits, PR review, merge, and deployment. An unrequested release does not block local delivery; a requested but blocked release remains incomplete. ## Trellis System -### Developer Identity +### Specs and Identity -On first use, initialize your identity: +Read relevant `.trellis/spec//index.md` and task-specific guidelines before coding. Some repositories have an additional package level. Discover actual paths with: ```bash -python3 ./.trellis/scripts/init_developer.py +python3 ./.trellis/scripts/get_context.py --mode packages ``` -Creates `.trellis/.developer` (gitignored) + `.trellis/workspace//`. - -### Spec System - -`.trellis/spec/` holds coding guidelines organized by package and layer. - -- `.trellis/spec///index.md` — entry point with **Pre-Development Checklist** + **Quality Check**. Actual guidelines live in the `.md` files it points to. -- `.trellis/spec/guides/index.md` — cross-package thinking guides. +Initialize identity only when a task/journal operation needs it and none exists: ```bash -python3 ./.trellis/scripts/get_context.py --mode packages # list packages / layers +python3 ./.trellis/scripts/init_developer.py ``` -**When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision. +### Task Commands -### Task System - -Every task has its own directory under `.trellis/tasks/{MM-DD-name}/` holding `task.json`, `prd.md`, optional `design.md`, optional `implement.md`, optional `research/`, and context manifests (`implement.jsonl`, `check.jsonl`) for sub-agent-capable platforms. +Use a task for product development or work benefiting from durable acceptance tracking. Simple answers, read-only audits, and narrow documentation/rule maintenance may run without one. Reuse matching tasks; preserve other sessions' active work. ```bash -# Task lifecycle -python3 ./.trellis/scripts/task.py create "" [--slug <name>] [--parent <dir>] -python3 ./.trellis/scripts/task.py start <name> # set active task (session-scoped when available) -python3 ./.trellis/scripts/task.py current --source # show active task and source -python3 ./.trellis/scripts/task.py finish # clear active task (triggers after_finish hooks) -python3 ./.trellis/scripts/task.py archive <name> # move to archive/{year-month}/ -python3 ./.trellis/scripts/task.py list [--mine] [--status <s>] -python3 ./.trellis/scripts/task.py list-archive - -# Code-spec context (injected into implement/check agents via JSONL). -# `implement.jsonl` / `check.jsonl` are seeded on `task create` for sub-agent-capable -# platforms; the AI curates real spec + research entries during planning when needed. +python3 ./.trellis/scripts/task.py current --source +python3 ./.trellis/scripts/task.py list +python3 ./.trellis/scripts/task.py create "<title>" --slug <name> +python3 ./.trellis/scripts/task.py start <name> python3 ./.trellis/scripts/task.py add-context <name> <action> <file> <reason> -python3 ./.trellis/scripts/task.py list-context <name> [action] python3 ./.trellis/scripts/task.py validate <name> - -# Task metadata -python3 ./.trellis/scripts/task.py set-branch <name> <branch> -python3 ./.trellis/scripts/task.py set-base-branch <name> <branch> # PR target -python3 ./.trellis/scripts/task.py set-scope <name> <scope> - -# Hierarchy (parent/child) -python3 ./.trellis/scripts/task.py add-subtask <parent> <child> -python3 ./.trellis/scripts/task.py remove-subtask <parent> <child> - -# PR creation -python3 ./.trellis/scripts/task.py create-pr [name] [--dry-run] +python3 ./.trellis/scripts/task.py finish +python3 ./.trellis/scripts/task.py archive <name> ``` -> Run `python3 ./.trellis/scripts/task.py --help` to see the authoritative, up-to-date list. - -**Current-task mechanism**: `task.py create` creates the task directory and (when session identity is available) auto-sets the per-session active-task pointer so the planning breadcrumb fires immediately. `task.py start` writes the same pointer (idempotent if already set) and flips `task.json.status` from `planning` to `in_progress`. State is stored under `.trellis/.runtime/sessions/`. If no context key is available from hook input, `TRELLIS_CONTEXT_ID`, or a platform-native session environment variable, there is no active task and `task.py start` fails with a session identity hint. `task.py finish` deletes the current session file (status unchanged). `task.py archive <task>` writes `status=completed`, moves the directory to `archive/`, and deletes any runtime session files that still point at the archived task. - -### Workspace System - -Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`. +`create` seeds `task.json` and `prd.md`, with optional context manifests; `--slug` sets the suffix of the `MM-DD-<slug>` directory. Use the returned task path. `start` sets `in_progress` and the session pointer. If session identity is missing, follow the command's hint using the real current session identifier. `finish` clears the pointer without completing the task. `archive` sets `completed`, moves the task, clears matching pointers, and can auto-commit. Inspect `--help` and configuration before commands with commit/external effects. -- `journal-N.md` — session log. **Max 2000 lines per file**; a new `journal-(N+1).md` is auto-created when exceeded. -- `index.md` — personal index (total sessions, last active). +Optional metadata, hierarchy, and PR commands are listed by `task.py --help`. Create parent/child tasks only for deliverables benefiting from independent acceptance and ownership; record dependencies explicitly. -```bash -python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary" -``` - -### Context Script +### Context and Journal ```bash -python3 ./.trellis/scripts/get_context.py # full session runtime -python3 ./.trellis/scripts/get_context.py --mode packages # available packages + spec layers -python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y> # detailed guide for a workflow step +python3 ./.trellis/scripts/get_context.py +python3 ./.trellis/scripts/get_context.py --mode phase +python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y> +python3 ./.trellis/scripts/add_session.py --title "Title" --commit "<actual-hash>" --summary "Summary" ``` ---- - -<!-- - WORKFLOW-STATE BREADCRUMB CONTRACT (read this before editing the tag blocks below) - - The [workflow-state:STATUS] blocks embedded in the ## Phase Index section - below are the SINGLE source of truth for the per-turn `<workflow-state>` - breadcrumb that every supported AI platform's UserPromptSubmit hook - reads. inject-workflow-state.py (Python platforms) and - inject-workflow-state.js (OpenCode plugin) only parse them — there is no - fallback dict baked into the scripts after v0.5.0-rc.0. - - STATUS charset: [A-Za-z0-9_-]+. When the hook can't find a tag, it - degrades to a generic "Refer to workflow.md for current step." line — - intentionally visible so users notice and fix a broken workflow.md. - - INVARIANT (test/regression.test.ts): - Every workflow-walkthrough step marked `[required · once]` must have a - matching enforcement line in its phase's [workflow-state:*] block. The - breadcrumb is the only per-turn channel; if a mandatory step isn't - mentioned there, the AI silently skips it (Phase 1 planning gate - skip and Phase 3.4 commit skip both manifested via this gap). - - TAG ↔ PHASE scoping: - [workflow-state:no_task] → no active task; before Phase 1 - [workflow-state:planning] → all of Phase 1 (status='planning') - [workflow-state:planning-inline] → Codex inline variant of Phase 1 - [workflow-state:in_progress] → Phase 2 + Phase 3.2-3.4 - (status stays 'in_progress' from - task.py start until task.py archive) - [workflow-state:in_progress-inline] → Codex inline variant of Phase 2/3 - [workflow-state:completed] → currently DEAD: cmd_archive flips - status and moves the dir in the same - call, so the resolver loses the - pointer (block kept for a future - explicit in_progress→completed - transition) - - Editing checklist: - - When you change a [workflow-state:STATUS] block, also check the - matching phase's `[required · once]` walkthrough steps for sync - - Run `trellis update` after editing to push the new bodies to - downstream user projects (block-level managed replacement) - - Full runtime contract: - .trellis/spec/cli/backend/workflow-state-contract.md ---> +Journal useful cross-session facts using actual task commits; do not invent hashes or create bookkeeping commits when the user requested no commits. Preserve lasting decisions or expensive-to-recover evidence. Routine reads, intermediate hypotheses, and every session do not require new documents. ## Phase Index ``` -Phase 1: Plan → classify, get task-creation consent, then write planning artifacts -Phase 2: Execute → implement only after task status is in_progress -Phase 3: Finish → verify, update spec, commit, and wrap up +Phase 1: Plan -> establish scope, acceptance, and necessary context +Phase 2: Execute -> implement and verify the authorized outcome +Phase 3: Finish -> resolve findings and perform authorized wrap-up ``` ### Request Triage -- Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session. -- Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split. -- User approval to create a task is not approval to start implementation. Planning still happens first. - -### Planning Artifacts - -- `prd.md` — requirements, constraints, and acceptance criteria. Do not put technical design or execution checklists here. -- `design.md` — technical design for complex tasks: boundaries, contracts, data flow, tradeoffs, compatibility, rollout / rollback shape. -- `implement.md` — execution plan for complex tasks: ordered checklist, validation commands, review gates, and rollback points. -- `implement.jsonl` / `check.jsonl` — spec and research manifests for sub-agent context. They do not replace `implement.md`. -- Lightweight tasks may be PRD-only. Complex tasks must have `prd.md`, `design.md`, and `implement.md` before `task.py start`. - -### Parent / Child Task Trees - -Use a parent task when one user request contains several independently verifiable deliverables. The parent task owns the source requirement set, the task map, cross-child acceptance criteria, and final integration review; it normally should not be the implementation target unless it also has direct work. - -Use child tasks for deliverables that can be planned, implemented, checked, and archived independently. Parent/child structure is not a dependency system: if one child must wait for another, write that ordering in the child `prd.md` / `implement.md` and keep each child's acceptance criteria testable. - -Create new children with `task.py create "<title>" --slug <name> --parent <parent-dir>`. Link existing tasks with `task.py add-subtask <parent> <child>`, and unlink mistakes with `task.py remove-subtask <parent> <child>`. - -<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) --> +- Determine the requested deliverable and existing authorization. No separate consent is needed to create a necessary local task or move from a sufficient plan into already requested implementation. +- Skip bookkeeping for simple answers, read-only audits, and narrow documentation/rule maintenance. Declining Trellis does not revoke an implementation request; continue inline with proportionate planning. +- Clarify only consequential unresolved intent or missing authorization. Continue independent work while awaiting an answer. +- `prd.md` records goal, constraints, and testable acceptance. Add `design.md` for durable decisions/contracts and `implement.md` for coordination or resumable execution only when useful. Neither is required merely because work is complex. +- Load `trellis-brainstorm` for material ambiguity, `trellis-before-dev` before coding, and `trellis-check` for verification. Unavailable commands or agent types do not prevent equivalent inline work. [workflow-state:no_task] -No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task. -Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session. -Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split. +Determine the requested outcome and reuse existing authorization. Answer or perform narrow rule/document maintenance inline; for product work, reuse/create a suitable local task without process consent. Plan proportionately, then start and implement if requested. Clarify only material missing intent or authorization; continue independent work. [/workflow-state:no_task] ### Phase 1: Plan -- 1.0 Create task `[required · once]` (only after task-creation consent) -- 1.1 Requirement exploration `[required · repeatable]` (`prd.md`; complex tasks also need `design.md` + `implement.md`) -- 1.2 Research `[optional · repeatable]` -- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix (sub-agent-dispatch platforms only; inline platforms skip) -- 1.4 Activate task `[required · once]` (review gate, then `task.py start`; status → in_progress) -- 1.5 Completion criteria -<!-- Per-turn breadcrumb: shown throughout Phase 1 (status='planning') --> +- 1.0 Create/reuse task `[when needed · once]` +- 1.1 Establish scope and acceptance `[required · once]` +- 1.2 Research `[on demand]` +- 1.3 Configure context `[when delegating · once]` +- 1.4 Activate task `[when using a task · once]` +- 1.5 Check readiness [workflow-state:planning] -Load `trellis-brainstorm`; stay in planning. -Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`. -Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position. -Sub-agent mode: curate `implement.jsonl` and `check.jsonl` as spec/research manifests before start. +Inspect evidence; use trellis-brainstorm only for material ambiguity. Record concise scope/acceptance in prd.md; add design/implementation documents only when useful. If independently delegating, supply relevant context. When implementation is authorized and no material blocker remains, run task.py start and continue without another approval. Planning-only requests end with the plan. [/workflow-state:planning] -<!-- Per-turn breadcrumb: shown throughout Phase 1 when codex.dispatch_mode=inline. - Codex-only opt-in alternate to [workflow-state:planning]. The main agent - edits code directly in Phase 2, so jsonl curation is skipped — - the inline workflow loads `trellis-before-dev` instead of injecting JSONL - into a sub-agent. --> - [workflow-state:planning-inline] -Load `trellis-brainstorm`; stay in planning. -Lightweight: `prd.md` can be enough. Complex: finish `prd.md`, `design.md`, and `implement.md`; ask for review before `task.py start`. -Multi-deliverable scope: consider a parent task plus independently verifiable child tasks; dependencies must be written in child artifacts, not implied by tree position. -Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-before-dev`. +Inspect evidence; use trellis-brainstorm only for material ambiguity. Record concise scope/acceptance in prd.md; add design/implementation documents only when useful. Read relevant specs directly; skip JSONL curation inline. When implementation is authorized and no material blocker remains, run task.py start and continue. Planning-only requests end with the plan. [/workflow-state:planning-inline] ### Phase 2: Execute -- 2.1 Implement `[required · repeatable]` -- 2.2 Quality check `[required · repeatable]` -- 2.3 Rollback `[on demand]` - -<!-- Per-turn breadcrumb: shown while status='in_progress'. - Scope: all of Phase 2 + Phase 3.2-3.4 (status stays 'in_progress' from - task.py start until task.py archive; only archive flips it). The body - therefore must cover every required step from implementation through - commit, including Phase 3.3 spec update and Phase 3.4 commit. --> -Sub-agent dispatch protocol applies to all platforms and all sub-agents, including class-2 Codex/Gemini/Qoder/Copilot/ZCode/Reasonix/Trae and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions. +- 2.1 Implement `[required for implementation requests]` +- 2.2 Quality check `[required · repeat after relevant changes]` +- 2.3 Replan or rollback `[on demand]` [workflow-state:in_progress] -Tools: `trellis-implement` / `trellis-research` are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent form when verifying after code changes. -Flow: `trellis-implement` -> `trellis-check` -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`. -Main-session default: dispatch implement/check sub-agents. Sub-agent self-exemption: if already running as `trellis-implement`, do NOT spawn another `trellis-implement` or `trellis-check`; if already running as `trellis-check`, do NOT spawn another `trellis-check` or `trellis-implement`. Dispatch is main session only. -Dispatch prompt starts with `Active task: <task path from task.py current>`. Read context: jsonl entries -> `prd.md` -> `design.md if present` -> `implement.md if present`. +Implement the authorized goal with task context and relevant specs. Default to direct execution; delegate only an independent bounded job when permitted and useful. Run proportionate checks, fix task-related findings, and do not repeat passing checks without new evidence. Assess spec updates (3.3), perform authorized commits (3.4), and execute finish-work (3.5). Report local/release status separately. trellis-implement is an agent type, not a skill; use callable tools or inline fallback. [/workflow-state:in_progress] -<!-- Per-turn breadcrumb: shown while status='in_progress' when - codex.dispatch_mode=inline. Codex-only opt-in alternate to - [workflow-state:in_progress]. The main session edits code directly - instead of dispatching sub-agents. --> - [workflow-state:in_progress-inline] -Flow: `trellis-before-dev` -> edit -> `trellis-check` -> validation -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`. -Do not dispatch implement/check sub-agents in inline mode. -Read context: `prd.md` -> `design.md if present` -> `implement.md if present`, plus relevant spec/research loaded by skills. +Use trellis-before-dev, implement inline, then trellis-check with proportionate validation. Fix task-related findings; do not repeat passing checks without new changes or concerns. Assess useful spec updates (3.3), perform authorized commits (3.4), and execute finish-work (3.5). Report local/release status separately; pending external authorization does not block independent local work. [/workflow-state:in_progress-inline] ### Phase 3: Finish -- 3.2 Debug retrospective `[on demand]` -- 3.3 Spec update `[required · once]` -- 3.4 Commit changes `[required · once]` -- 3.5 Wrap-up reminder - -> Note: step 3.1 was folded into 2.2 (last-iteration full-scope check) and 3.4 (commit preamble). Numbering kept stable to avoid breaking external references. -<!-- Per-turn breadcrumb: shown while status='completed'. - Currently DEAD in normal flow: cmd_archive writes status='completed' in - the same call that moves the task dir to archive/, so the active-task - resolver loses the pointer and the hook never fires on archived tasks. - Block preserved for a future status-transition redesign (e.g. an - explicit in_progress→completed command). Edit through the same spec - channel as the live blocks. --> +- 3.2 Debug retrospective `[on demand]` +- 3.3 Assess spec update `[required · once; write only if useful]` +- 3.4 Commit changes `[when authorized]` +- 3.5 Wrap up `[required within requested scope]` [workflow-state:completed] -Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first. +Verify acceptance and execute authorized finish-work steps. Preserve unrelated dirty paths. Commit/release status is separate from local completion; never archive unfinished acceptance or bypass PR review to clear a status. [/workflow-state:completed] -### Rules - -1. Identify which Phase you're in, then continue from the next step there -2. Run steps in order inside each Phase; `[required]` steps can't be skipped -3. Phases can roll back (e.g., Execute reveals a prd defect → return to Plan to fix, then re-enter Execute) -4. Steps tagged `[once]` are skipped if the output already exists; don't re-run -5. Artifact presence informs the next step; missing `design.md` / `implement.md` is valid for lightweight tasks and incomplete planning for complex tasks. - -### Active Task Routing - -When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed. - -[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -- Planning or unclear requirements -> `trellis-brainstorm`. -- `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`. -- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`. - -[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -[codex-inline, Kilo, Antigravity, Devin] - -- Planning or unclear requirements -> `trellis-brainstorm`. -- Before editing -> `trellis-before-dev`; after editing -> `trellis-check`. -- Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`. +### Routing and Completion Rules -[/codex-inline, Kilo, Antigravity, Devin] +Resume the first unfinished applicable step. Do not redo planning or approvals because a phase changed. Revisit only facts affected by new evidence/scope; missing optional documents are not blockers. Carry forward authorization when returning from review to implementation. -### Guardrails - -- Task creation approval is not implementation approval; implementation waits for `task.py start` after artifact review. -- PRD-only is valid for lightweight tasks; complex tasks need `design.md` + `implement.md`. -- Planning must be persisted to task artifacts; checks must run before reporting completion. - -### Loading Step Detail - -At each step, run this to fetch detailed guidance: - -```bash -python3 ./.trellis/scripts/get_context.py --mode phase --step <step> -# e.g. python3 ./.trellis/scripts/get_context.py --mode phase --step 1.1 -``` - ---- +Use `/trellis:continue` or `/trellis:finish-work` when callable. Otherwise read `.claude/commands/trellis/continue.md` or `.claude/commands/trellis/finish-work.md` and perform equivalent steps directly. Taskless work follows the same acceptance/verification principles without manufacturing a task or journal. ## Phase 1: Plan -Goal: classify the request, get task-creation consent when a task is needed, and produce the planning artifacts required before implementation. - -#### 1.0 Create task `[required · once]` - -Create the task directory only after task-creation consent. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available: - -```bash -python3 ./.trellis/scripts/task.py create "<task title>" --slug <name> -``` - -`--slug` is the human-readable name only. Do **not** include the `MM-DD-` date prefix; `task.py create` adds that prefix automatically. - -For task trees, create the parent task first and then create each child with `--parent <parent-dir>`. Do not start the parent just because children exist; start the child that owns the next independently verifiable deliverable. - -After this command succeeds, the per-turn breadcrumb auto-switches to `[workflow-state:planning]`, telling the AI to stay in planning. - -Run only `create` here — do not also run `start`. `start` flips status to `in_progress`, which switches the breadcrumb to the implementation phase before planning artifacts are reviewed. Save `start` for step 1.4. - -Skip when `python3 ./.trellis/scripts/task.py current --source` already points to a task. - -#### 1.1 Requirement exploration `[required · repeatable]` - -Load the `trellis-brainstorm` skill and explore requirements interactively with the user per the skill's guidance. - -The brainstorm skill will guide you to: -- Ask one question at a time -- Prefer researching over asking the user -- Prefer offering options over open-ended questions -- Update `prd.md` immediately after each user answer -- Split large scopes into a parent task plus child tasks when the deliverables can be verified independently -- Keep `prd.md` focused on requirements and acceptance criteria -- For complex tasks, produce `design.md` and `implement.md` before implementation starts - -When considering a parent/child split: -- Use a parent task when one request contains several independently verifiable deliverables. -- Parent tasks own source requirements, child-task mapping, cross-child acceptance criteria, and final integration review. -- Child tasks own actual deliverables that can be planned, implemented, checked, and archived independently. -- Parent/child structure is not a dependency system. If child B depends on child A, write that ordering in child B's `prd.md` / `implement.md`. -- Start the child task that owns the next deliverable. Do not start the parent unless the parent itself has direct implementation work. - -Return to this step whenever requirements change and revise the relevant artifact. - -#### 1.2 Research `[optional · repeatable]` - -Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc. - -[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -Spawn the research sub-agent: - -- **Agent type**: `trellis-research` -- **Task description**: Research <specific question> -- **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/` - -[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -[codex-inline, Kilo, Antigravity, Devin] - -Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. (For `codex-inline` this avoids the `fork_turns="none"` isolation that prevents `trellis-research` sub-agents from resolving the active task path.) - -[/codex-inline, Kilo, Antigravity, Devin] - -**Research artifact conventions**: -- One file per research topic (e.g. `research/auth-library-comparison.md`) -- Record third-party library usage examples, API references, version constraints in files -- Note relevant spec file paths you discovered for later reference - -Brainstorm and research can interleave freely — pause to research a technical question, then return to talk with the user. - -**Key principle**: Research output must be written to files, not left only in the chat. Conversations get compacted; files don't. - -#### 1.3 Configure context `[required · once]` - -[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries. - -**Location**: `{TASK_DIR}/implement.jsonl` and `{TASK_DIR}/check.jsonl` (already exist). +#### 1.0 Create/reuse task `[when needed · once]` -**Format**: one JSON object per line — `{"file": "<path>", "reason": "<why>"}`. Paths are repo-root relative. +Before any file writes, including task creation, check `git status --short --branch` and `git branch --show-current`. On `main` or detached HEAD, create a task branch first, preserving existing changes. Follow AGENTS.md for Issue/README synchronization and external authorization; remote access must not block independent local work. -**What to put in**: -- **Spec files** — `.trellis/spec/<package>/<layer>/index.md` and any specific guideline files (`error-handling.md`, `conventions.md`, etc.) relevant to this task -- **Research files** — `{TASK_DIR}/research/*.md` that the sub-agent will need to consult +Then check `task.py current --source` and `task.py list`. Reuse a matching task; create one for product work or useful durable coordination without asking process consent. Simple answers, read-only audits, and narrow documentation/rule maintenance need no task. Honor an explicit request to skip Trellis with a proportionate inline plan. -**What NOT to put in**: -- Code files (`src/**`, `packages/**/*.ts`, etc.) — those are read by the sub-agent during implementation, not pre-registered here -- Files you're about to modify — same reason +#### 1.1 Establish scope and acceptance `[required · once]` -**Split between the two files**: -- `implement.jsonl` → specs + research the implement sub-agent needs to write code correctly -- `check.jsonl` → specs for the check sub-agent (quality guidelines, check conventions, same research if needed) +Inspect relevant code, current instructions, and decisions. Define the outcome, boundaries, and acceptance evidence in a concise PRD or inline plan. Use `trellis-brainstorm` for consequential ambiguity; choose routine implementation details yourself. Ask the smallest useful set of questions and continue independent work. -These manifests do not replace `implement.md`. `implement.md` is the human-readable execution plan for a complex task; jsonl files only list context files to inject or load. +Add design/implementation documents only when their separate purpose justifies them. Do not split tasks or rewrite a sufficient PRD merely for a formatting gate. Update the plan when evidence changes scope/acceptance. -**How to discover relevant specs**: +#### 1.2 Research `[on demand]` -```bash -python3 ./.trellis/scripts/get_context.py --mode packages -``` - -Lists every package + its spec layers with paths. Pick the entries that match this task's domain. - -**How to append entries**: - -Either edit the jsonl file directly in your editor, or use: - -```bash -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>" -python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>" -``` - -Delete the seed `_example` line once real entries exist (optional — it's skipped automatically by consumers). +Research specific uncertainty using available local/external tools and stop when evidence is sufficient. Preserve reusable decisions, exact contracts, or expensive-to-recover evidence in existing documents; routine findings need no standalone file. -Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one real `{"file": "...", "reason": "..."}` entry before `task.py start`. The seed `_example` row alone is not ready. - -Skip this step only when both files already have real curated entries. - -[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -[codex-inline, Kilo, Antigravity, Devin] - -Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2. - -[/codex-inline, Kilo, Antigravity, Devin] - -#### 1.4 Activate task `[required · once]` - -After artifact review, flip the task status to `in_progress`: - -```bash -python3 ./.trellis/scripts/task.py start <task-dir> -``` +Direct research is the default. Delegate only when authorized, useful, and independent of main-session work, with a bounded question, context, expected output, and completion criteria. Unavailable agent tooling is not a blocker. -For lightweight tasks, `prd.md` can be enough. For complex tasks, `prd.md`, `design.md`, and `implement.md` must exist and be reviewed before start. On sub-agent-dispatch platforms, `implement.jsonl` and `check.jsonl` must both have real curated entries before start. Runtime consumers tolerate missing or seed-only manifests for compatibility, but that tolerance is not a planning-ready state. +#### 1.3 Configure context `[when delegating · once]` -After this command succeeds, the breadcrumb auto-switches to `[workflow-state:in_progress]`, and the rest of Phase 2 / 3 follows. +Curate `implement.jsonl` / `check.jsonl` only if an actual dispatched agent consumes them. Relevant entries use `{"file": "<repo-relative-path>", "reason": "<why-needed>"}`; remove or ignore `_example` rows. Supply the task path and role explicitly instead of assuming a shared session pointer. -If `task.py start` errors with a session-identity message (no context key from hook input, `TRELLIS_CONTEXT_ID`, or platform-native session env), follow the hint in the error to set up session identity, then retry. +Load relevant specs/research, then `prd.md`, `design.md` if present, and `implement.md` if present. Inline execution reads context directly and skips JSONL bookkeeping. Do not make unused manifests a prerequisite. -#### 1.5 Completion criteria +#### 1.4 Activate task `[when using a task · once]` -| Condition | Required | -|------|:---:| -| `prd.md` exists | ✅ | -| User confirms task should enter implementation | ✅ | -| `task.py start` has been run (status = in_progress) | ✅ | -| `research/` has artifacts (complex tasks) | recommended | -| `design.md` exists (complex tasks) | ✅ | -| `implement.md` exists (complex tasks) | ✅ | +When scope/acceptance are sufficient and implementation was requested, run `python3 ./.trellis/scripts/task.py start <task-dir>` and continue. No second approval is needed for planning, creating a task, or implementation within existing authorization. Deliver planning-only/review-only requests without implementation. -[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] +If session identity setup fails, follow the real error and inspect the environment. Preserve other session pointers and do not invent a shared identity. Complete independent preparation and report a persistent tool blocker precisely. -| `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ | +#### 1.5 Check readiness -[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - ---- +Required: a clear enough goal and acceptance, relevant context, and authorization for the next action. Task-backed implementation also activates its task. Optional documents, interviews, research, and manifests are needed only for a concrete purpose. Clarify remaining consequential blockers; proceed on reversible details using repository patterns. ## Phase 2: Execute -Goal: turn reviewed planning artifacts into code that passes quality checks. - -#### 2.1 Implement `[required · repeatable]` - -[Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi] - -Spawn the implement sub-agent: - -- **Agent type**: `trellis-implement` -- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check -- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`. - -The platform hook/plugin auto-handles: -- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt -- Injects `prd.md`, `design.md` if present, and `implement.md` if present - -[/Claude Code, Cursor, OpenCode, CodeBuddy, Droid, Pi] - -[codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae] - -Spawn the implement sub-agent: - -- **Agent type**: `trellis-implement` -- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check -- **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`. - -The pull-based sub-agent definition auto-handles the context load requirement: -- Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present -- Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding - -[/codex-sub-agent, Gemini, Qoder, Copilot, ZCode, Reasonix, Trae] - -[Kiro] - -Spawn the implement sub-agent: - -- **Agent type**: `trellis-implement` -- **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check -- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`. - -The platform prelude auto-handles the context load requirement: -- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt -- Injects `prd.md`, `design.md` if present, and `implement.md` if present - -[/Kiro] - -[codex-inline, Kilo, Antigravity, Devin] - -1. Load the `trellis-before-dev` skill to read project guidelines -2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present -3. Consult materials under `{TASK_DIR}/research/` -4. Implement the code per reviewed artifacts -5. Run project lint and type-check +#### 2.1 Implement `[required for implementation requests]` -[/codex-inline, Kilo, Antigravity, Devin] +Load `trellis-before-dev` when coding, read relevant context, and implement the requested outcome directly. Preserve unrelated changes and scope. Prefer existing APIs/patterns; add abstractions only for demonstrated complexity or meaningful duplication. -#### 2.2 Quality check `[required · repeatable]` +Delegate only a concrete independent task that improves time/quality when active instructions permit it. Platform support does not require delegation. Include `Active task: <task path>` when present, role, owned files, inputs, output, and completion criteria. Dispatched agents execute their roles without recursively spawning the same implement/check role. If an agent type is unavailable, work inline. -[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] +#### 2.2 Quality check `[required · repeat after relevant changes]` -Spawn the check sub-agent: +Use `trellis-check` or direct equivalent. Review the entire current task diff against acceptance and relevant contracts. Run required repository checks applicable to affected layers and meaningful tests scaled to risk. Shared behavior/cross-layer contracts justify broader checks; prose/rule changes normally need consistency, references, and parser checks rather than the application test suite. -- **Agent type**: `trellis-check` -- **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass -- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`. +Fix issues introduced by this task or necessary for its goal. Separate unrelated failures and environment limits from regressions. Rerun affected checks after relevant fixes. Once sufficient checks pass, proceed; broaden/repeat only for new changes, failures, or unresolved concerns. Do not change unrelated systems merely to make all checks green. -The check agent's job: -- Review code changes against specs -- Review code changes against `prd.md`, `design.md` if present, and `implement.md` if present -- Auto-fix issues it finds -- Run lint and typecheck to verify +#### 2.3 Replan or rollback `[on demand]` -[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, ZCode, Reasonix, Trae] - -[codex-inline, Kilo, Antigravity, Devin] - -Load the `trellis-check` skill and verify the code per its guidance: -- Spec compliance -- lint / type-check / tests -- Cross-layer consistency (when changes span layers) - -If issues are found → fix → re-check, until green. - -[/codex-inline, Kilo, Antigravity, Devin] - -**Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot. - -#### 2.3 Rollback `[on demand]` - -- `check` reveals a prd defect → return to Phase 1, fix `prd.md`, then redo 2.1 -- Implementation went wrong → revert code, redo 2.1 -- Need more research → research (same as Phase 1.2), write findings into `research/` - ---- +Update scope/acceptance when evidence requires it, preserving existing authorization. Recover your own attributable changes with targeted edits; never revert user work or perform destructive history operations without authorization. For repeated failure, use `trellis-break-loop` to change the hypothesis or diagnostic method. Report exact persistent input/access blockers after completing independent work. ## Phase 3: Finish -Goal: ensure code quality, capture lessons, record the work. - #### 3.2 Debug retrospective `[on demand]` -If this task involved repeated debugging (the same issue was fixed multiple times), load the `trellis-break-loop` skill to: -- Classify the root cause -- Explain why earlier fixes failed -- Propose prevention - -The goal is to capture debugging lessons so the same class of issue doesn't recur. - -#### 3.3 Spec update `[required · once]` - -Load the `trellis-update-spec` skill and review whether this task produced new knowledge worth recording: -- Newly discovered patterns or conventions -- Pitfalls you hit -- New technical decisions - -Update the docs under `.trellis/spec/` accordingly. Even if the conclusion is "nothing to update", walk through the judgment. - -#### 3.4 Commit changes `[required · once]` - -**Spec-sync preamble**: before drafting commits, ask: did this task fix a bug or surface non-obvious knowledge that should land in `.trellis/spec/` so future-you (or future-AI) doesn't repeat the mistake? If yes, return to Phase 3.3 first — spec writes belong in the same task's commit batch, not as a forgotten follow-up. - -The AI drives a batched commit of this task's code changes so `/finish-work` can run cleanly afterwards. Goal: produce work commits FIRST, then bookkeeping (archive + journal) commits land after — never interleaved. - -**Step-by-step**: - -1. **Inspect dirty state**: - ```bash - git status --porcelain - ``` - Snapshot every dirty path. If the working tree is clean, skip to 3.5. - -2. **Learn commit style** from recent history (so drafted messages blend in): - ```bash - git log --oneline -5 - ``` - Note the prefix convention (`feat:` / `fix:` / `chore:` / `docs:` ...), language (中文/English), and length style. +Use `trellis-break-loop` for repeated failed fixes or a non-obvious cause worth preserving. Record a concise causal explanation and concrete prevention only where useful. Routine successful fixes need no retrospective document. -3. **Classify dirty files into two groups**: - - **AI-edited this session** — files you wrote/edited via Edit/Write/Bash tool calls in this session. You know what changed and why. - - **Unrecognized** — dirty files you did NOT touch this session (could be the user's manual edits, leftover WIP from a previous session, or unrelated work). Do NOT silently include these. +#### 3.3 Assess spec update `[required · once; write only if useful]` -4. **Draft a commit plan**. Group AI-edited files into logical commits (1 commit per coherent change unit, not 1 commit per file). Each entry: `<commit message>` + file list. List unrecognized files separately at the bottom. +Determine whether changed contracts or reusable non-obvious knowledge require a spec update; use `trellis-update-spec` for that change. Reuse the owning document and keep it proportional. Routine features/fixes do not automatically require a guide, seven-section template, or duplicated notes. If nothing useful changed, proceed without another artifact or confirmation. -5. **Present the plan once, ask for one-shot confirmation**. Format: - ``` - Proposed commits (in order): - 1. <message> - - <file> - - <file> - 2. <message> - - <file> +#### 3.4 Commit changes `[when authorized]` - Unrecognized dirty files (NOT in any commit — confirm include/exclude): - - <file> - - <file> +Check branch/status, inspect task changes, and run applicable checks. All commits belong on a task branch, never `main` or detached HEAD. Group task-owned changes into coherent commits using repository conventions. - Reply 'ok' / '行' to execute. Reply with edits, or '我自己来' / 'manual' to abort. - ``` +When commits are authorized, execute without another plan-approval prompt. Stage identified task changes only, selecting hunks for mixed files. Preserve unrelated dirty paths; inspect before asking the user to classify them. If commits are not authorized or local-only edits were requested, retain the verified diff and continue applicable wrap-up. Ask for commit authorization only when the requested outcome requires it. -6. **On confirmation**: run `git add <files>` + `git commit -m "<msg>"` for each batch in order. Do not amend. Do not push. +Inspect archive/journal auto-commit behavior; bookkeeping cannot bypass a no-commit instruction. Do not amend published history or push without corresponding authorization. Integration to `main` requires a PR and completed Codex review of its latest commit per AGENTS.md. -7. **On rejection** (user replies "不行" / "我自己来" / "manual" / any pushback on the plan): stop. Do not attempt a second plan. The user will commit by hand; you skip ahead to 3.5 once they confirm. +#### 3.5 Wrap up `[required within requested scope]` -**Rules**: -- No `git commit --amend` anywhere — three-stage three-commit flow (work commits → archive commit → journal commit). -- Never push to remote in this step. -- If the user wants different message wording but accepts the file grouping, edit the message and re-confirm once — but if they reject the grouping, exit to manual mode. -- The batched plan is one prompt; do not prompt per commit. +Execute applicable `.claude/commands/trellis/finish-work.md` steps instead of leaving a reminder. Verify acceptance, preserve useful context, and perform authorized task/Issue/README cleanup. Archive only when the task's acceptance is met; session end or a commit alone is insufficient. Skip unrelated tasks and unnecessary bookkeeping. -#### 3.5 Wrap-up reminder +Report the delivered change, verification, and remaining requested steps/blockers. Distinguish local completion, commits, review, merge, and deployment when relevant. Finish independent work before handing back a missing authorization question. Unrequested external actions must not obstruct local delivery. -After the above, remind the user they can run `/finish-work` to wrap up (archive the task, record the session). - ---- - -## Customizing Trellis (for forks) - -This section is for developers who want to modify the Trellis workflow itself. All customization is done by editing this file; the scripts are parsers only. - -### Changing what a step means - -Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants: -- No active task must triage first and ask for task-creation consent before creating a Trellis task. -- Planning must distinguish lightweight PRD-only tasks from complex tasks that require `prd.md`, `design.md`, and `implement.md` before start. -- Every required execution path must keep the Phase 3.4 commit reminder reachable before `/trellis:finish-work`. - -All tag blocks live in the `## Phase Index` section above, immediately after each phase summary: - -| Scope | Corresponding tag | -|---|---| -| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) | -| All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) | -| Codex inline Phase 1 | `[workflow-state:planning-inline]` | -| Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) | -| Codex inline Phase 2 + Phase 3.2–3.4 | `[workflow-state:in_progress-inline]` | -| After Phase 3.5 (archived) | `[workflow-state:completed]` (after Phase 3 summary; **currently DEAD**) | - -### Changing the per-turn prompt text - -Directly edit the body of the corresponding `[workflow-state:STATUS]` block. After editing, run `trellis update` (if you're a template maintainer) or restart your AI session (if you're customizing your own project) — no script changes required. - -### Adding a custom status - -Add a new block: - -``` -[workflow-state:my-status] -your per-turn prompt text -[/workflow-state:my-status] -``` - -Constraints: -- STATUS charset: `[A-Za-z0-9_-]+` (underscores and hyphens allowed, e.g. `in-review`, `blocked-by-team`) -- A lifecycle hook must write `task.json.status` to your custom value, otherwise the tag is never read -- Lifecycle hooks live in `task.json.hooks.after_*` and bind to one of `after_create / after_start / after_finish / after_archive` - -### Adding a lifecycle hook - -Add a `hooks` field to your `task.json`: - -```json -{ - "hooks": { - "after_finish": [ - "your-script-or-command-here" - ] - } -} -``` +## Customizing Trellis -Supported events: `after_create / after_start / after_finish / after_archive`. Note that `after_finish` ≠ a status change (it only clears the active-task pointer); use `after_archive` for "task is done" notifications. +This is the project workflow source. Keep the Phase Index, numbered walkthrough, continue/finish-work commands, and related skills consistent. Edit conflicting old rules directly instead of stacking overrides. -### Full contract +Hooks read `[workflow-state:STATUS]` blocks. Preserve matched tags and current names: `no_task`, `planning`, `planning-inline`, `in_progress`, `in_progress-inline`, `completed`. Extraction uses `## Phase Index`, `## Phase 1: Plan`, and `#### X.Y` headings. Represent required steps in their state blocks. `completed` is normally unreachable after archive removes the pointer; keep it consistent for other consumers. -For the workflow state machine's runtime contract, the locations of all status writers, pseudo-statuses (`no_task` / `stale_<source_type>`), the hook reachability matrix, and other deep details, see: +For new statuses, update lifecycle writers and routing as well as tags. `after_finish` clears a pointer; `after_archive` represents completion. Inspect installed scripts/configuration instead of assuming upstream source paths exist. -- `.trellis/spec/cli/backend/workflow-state-contract.md` — runtime contract + writer table + test invariants -- `.trellis/scripts/inject-workflow-state.py` — actual parser (reads workflow.md only, no embedded text) +Trellis upgrades may regenerate managed instructions. Preserve project policy when reviewing an upgrade diff; do not run `trellis update` merely to apply local prose edits. diff --git a/AGENTS.md b/AGENTS.md index 1780b49..4ca79a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,9 +29,9 @@ Managed by Trellis. Edits outside this block are preserved; edits inside may be python3 .trellis/scripts/task.py current python3 .trellis/scripts/task.py list -# 任务生命周期（先规划、批准后才动代码；一个里程碑一个 commit） +# 任务生命周期（执行请求已授权规划和实现；按可独立审查的变更组织 commit） python3 .trellis/scripts/task.py create "<标题>" --slug <slug> # 建任务目录 -# → 填 <task>/prd.md（需求+验收标准）；复杂任务再写 design.md、implement.md +# → 填 <task>/prd.md（需求+验收标准）；仅在有独立用途时加 design.md、implement.md python3 .trellis/scripts/task.py start <slug> # 状态 → in_progress，才可实现 python3 .trellis/scripts/task.py archive <slug> # 完成后归档（自动 commit） @@ -39,14 +39,22 @@ python3 .trellis/scripts/task.py archive <slug> # 完成后归 python3 .trellis/scripts/get_context.py --mode phase --step 2.1 # 某一步的详细指引 python3 .trellis/scripts/get_context.py --mode packages # 列出 spec 层 -# 会话结束记 journal（用实际 commit hash） +# 有跨会话记录价值且允许提交时记 journal（用实际 commit hash） python3 .trellis/scripts/add_session.py --title "..." --commit "<hash1,hash2>" --summary "..." # 跨会话记忆（之前怎么讨论/解决的） trellis mem search "<关键词>" ``` -写代码前必读对应层的规范：`.trellis/spec/backend/`（改 CLI 先看 `cli-agent-contract.md`，错误处理看 `error-handling.md`）；前端看 `.trellis/spec/frontend/`。任务上下文的阅读顺序：`implement.jsonl` 清单 → `prd.md` → `design.md` → `implement.md`。 +写代码前必读对应层的规范：`.trellis/spec/backend/`（改 CLI 先看 `cli-agent-contract.md`，错误处理看 `error-handling.md`）；前端看 `.trellis/spec/frontend/`。有任务时读取现有上下文：实际使用的 `implement.jsonl` 清单 → `prd.md` → 存在的 `design.md`、`implement.md`；inline 工作直接读相关规范，不为读取顺序补建文件。 + +## 授权与完成 + +- 用户要求实现、修复或优化时，授权覆盖目标内必要的调查、规划、文件修改和验证；建任务、进入实现、已有授权范围内的提交不再逐项确认。用户明确要求仅审阅或仅规划时，停在该交付边界。 +- 先从当前会话、代码和项目记录找答案。仅在缺失信息会实质改变目标、正确性或产生难以撤销的后果时澄清；可逆的实现选择自行判断并说明关键假设。等待答案期间继续不依赖该答案的工作。 +- 仅在具体动作超出已有授权时请求批准，例如新增对外影响、费用承诺、访问范围或不可逆操作。先完成已授权的准备、验证和可审查结果，再说明缺失哪项授权；同一授权在会话中持续有效。 +- 简单说明、只读审阅和局部文档/规则维护可直接执行；产品开发按下述任务同步规范跟踪。复杂度决定计划与验证深度，不自动要求多份文档、子任务或子 Agent。 +- 完成以用户目标和验收证据为准。执行所有已授权收尾，分别说明本地交付、提交、PR、合并和发布状态；未请求的发布不阻塞本地交付，已请求但受阻的步骤不得宣称完成。保留无关修改，只修复本次引入或阻碍目标的问题。 ## 分支与 worktree 规范（强制） @@ -107,10 +115,10 @@ docker ps | grep echolog-db 产品路线和任务必须在 README、Trellis、GitHub Issue 三处保持可追踪的一致关系： 1. README 只维护方向、优先级和里程碑；Trellis task 维护 PRD、设计、实现清单、负责人和验收；GitHub Issue 维护公开讨论、依赖和关闭记录。 -2. 开发前先确认三处是否指向同一个任务，认领对应 Issue，并执行 `python3 .trellis/scripts/task.py start <slug>`。未认领、未激活的任务不得直接改代码。 -3. 一个会话只保留一个当前激活任务；一个父任务下可以挂独立可验收的子任务。完成的任务必须先通过验收，再关闭 Issue、归档 Trellis task，并更新 README。 -4. “清除”只清除活跃状态，不删除历史：使用 `task.py finish/archive` 和关闭 Issue，保留归档任务、Issue 和提交记录。 -5. 三处冲突时，以已验证实现和 Trellis task 为准，必须在同一变更中同步修正文档和 Issue。 +2. 产品开发前检查三处关联并复用或建立必要的本地 Trellis task，执行 `python3 .trellis/scripts/task.py start <slug>`。已有 GitHub 写入授权时认领 Issue；缺少授权或远端不可用时先完成本地实现与验证，记录待同步项，不以远端认领阻塞本地工作。局部文档/规则维护不强制创建 Issue 或 task。 +3. 一个会话只保留一个当前激活任务；只有独立验收确有帮助时才拆子任务。通过任务范围内的验收后执行已授权的收尾；仅当 README 路线或里程碑发生变化时更新它。Issue 关闭和 Trellis 归档应如实反映范围内的合并/发布要求，不把会话结束等同任务完成。 +4. 只清除活跃状态时用 `task.py finish`；任务达到验收后才归档或关闭对应 Issue。保留历史任务、Issue 和提交记录，不把清除状态当作完成。 +5. 三处冲突时，以已验证实现和 Trellis task 为准，在本次变更中修正本地文档，并在授权范围内同步 Issue；无法完成的远端同步明确列为待办。 ## Pull Request 与 Codex 审阅规范