# 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 --- ## Trellis System ### Developer Identity On first use, initialize your identity: ```bash python3 ./.trellis/scripts/init_developer.py ``` 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. ```bash python3 ./.trellis/scripts/get_context.py --mode packages # list packages / layers ``` **When to update spec**: new pattern/convention found · bug-fix prevention to codify · new technical decision. ### 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`). ```bash # Task lifecycle python3 ./.trellis/scripts/task.py create "" [--slug <name>] [--parent <dir>] python3 ./.trellis/scripts/task.py start <name> python3 ./.trellis/scripts/task.py finish python3 ./.trellis/scripts/task.py archive <name> python3 ./.trellis/scripts/task.py list [--mine] [--status <s>] ``` ### Workspace System Records every AI session for cross-session tracking under `.trellis/workspace/<developer>/`. - `journal-N.md` — session log. Max 2000 lines per file. - `index.md` — personal index (total sessions, last active). ```bash python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash" --summary "Summary" ``` ### Context Script ```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 ``` --- ## 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 ``` ### Classification - 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. - `implement.md` — execution plan for complex tasks: ordered checklist, validation commands, review gates. ### Skill Routing | User intent | Skill | |-------------|-------| | Wants a new feature / requirement unclear | trellis-brainstorm | | About to write code / start implementing | trellis-before-dev | | Finished writing / want to verify | trellis-check | | Stuck / fixed same bug several times | trellis-break-loop | | Spec needs update | trellis-update-spec | | Customize Trellis workflow | trellis-meta | [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. [/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 Activate task `[required · once]` (review gate, then task.py start; status → in_progress) [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. [/workflow-state:planning] ### Phase 2: Execute - 2.1 Implement `[required · repeatable]` - 2.2 Quality check `[required · repeatable]` [workflow-state:in_progress] Main session dispatches trellis-implement → trellis-check → update-spec → commit. Dispatch prompt starts with `Active task: <task path>`. Read context: prd.md → design.md if present → implement.md if present. [/workflow-state:in_progress] ### Phase 3: Finish - 3.2 Debug retrospective `[on demand]` (if repeated debugging, run trellis-break-loop) - 3.3 Spec update `[required · once]` (run trellis-update-spec to capture new knowledge) - 3.4 Commit changes `[required · once]` [workflow-state:completed] Code committed. Work done — session can wrap up. [/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 5. Artifact presence informs the next step; missing design.md / implement.md is valid for lightweight tasks