| name | ipix-task-lifecycle |
| description | Five-phase orchestrator for iPix / FashionOS Linear team IPI — plan, research, implement, test, ship (worktrees, verify matrix, PR workflow, Linear state). Use whenever implementing or shipping IPI-NNN, forensic verify before Done, multi-file platform work across src/mastra, CopilotKit, Next, Supabase, or user says "implement IPI-", "ship IPI-", "/task IPI", "close out Linear", "next P0 task", "forensic verify", "wiring plan", "open PR with verify". Always use for multi-step iPix delivery. Do NOT use for one-line typo fixes, explain-only questions, isolated copilotkit/ supabase/migration/lean/release-notes tasks without full lifecycle, or non-iPix repos.
|
| version | 1.8.0 |
ipix-task-lifecycle
BLUF: One hub, five phases, one bookkeeping contract for iPixai (team IPI). Live Linear is the execution contract. This repo has no docs/linear/issues/ or tasks/plan/todo.md yet — do not recreate them unless asked.
iPixai gates: docs/mastra/10-mastra-convert.md · split dev:ui / dev:agent · no prod Supabase writes · no wholesale old-Mastra copy. Graphify is optional (no graph in this repo).
Hub index: README.md · v1.8.0 — domain-skill routing, worktree gates, verify-matrix link, tracker path fix
/task IPI-NNN — default flow
Read docs/linear/issues/IPI-*.md + Linear (MCP or script)
→ **Skills:** line → Read each .claude/skills/<slug>/SKILL.md
→ worktree:audit → worktree:add OR worktree:health (existing wt)
→ Phase 1 skip? only if A–E + Skills + prompt lint + spec md synced (below)
→ Phase 2 skip? ≤3 files, no Supabase/RLS/edge/Mastra
→ Multi-file / unfamiliar? graphify query|path before reading source
→ Phase 3: Step 1b pre-edit gate → implement one A–E step at a time
→ Phase 4 verify matrix ([pr-workflow](../pr-workflow/references/verify-matrix.md))
→ pr-workflow: PR open · Bugbot · resolve threads
→ task-verifier (mandatory before Done on ship gates)
→ Phase 5: tasks/plan/todo.md 🟢 · Linear Done
When to invoke
Don't invoke for
- One-off questions or trivial single-file edits
- Commit-only with no Linear traceability
iPix context
| Topic | Rule |
|---|
| Linear | linear.app/amo100 · team IPI · LINEAR_API_KEY in .env.local |
| Linear read | Linear MCP get_issue when connected; else node scripts/linear-update-issue.mjs / spec md |
| Linear status | Linear MCP save_issue (In Progress / Done) — verify tool name in session; fallback scripts in shipping.md |
| Supabase | Remote linked · project nvdlhrodvevgwdsneplk · service role via API routes only |
| App | Next.js :3002 · app/ · (operator) route group |
| Tracker | tasks/plan/todo.md — not root todo.md |
| Issue IDs | IPI-NNN (Linear) — old PLT-/AI-/DNA-/COM-/UI- spec IDs are retired |
Worktree contract
Before any multi-step implementation — full detail: worktrees.
| When | Command |
|---|
| Before add | npm run worktree:audit |
| Create | npm run worktree:add -- IPI-NNN short-slug |
| Existing wt, before code | npm run worktree:health |
| Before remove | npm run worktree:pre-delete |
Never push to main. Branch: ipi/<id>-<slug>.
Child skills (load on demand)
Process skills (how to plan/ship)
Domain skills (what to build — mandatory in Phase 1)
When creating or enriching a task, Read each domain skill from .claude/skills/<slug>/SKILL.md before writing AC.
Router: references/domain-skill-routing.md · task inventory: tasks/intelligence/ai/skill-map.md
Full path-heuristic table → domain-skill-routing.md.
Sibling skills (not symlinked)
Routing tree
New / ambiguous → brainstorming → writing-plans → Phase 3
Linear issue w/ A–E + spec md + Skills → phases 2–5
Large / architecture → feature-dev → graphify → writing-plans → Phase 3
MVP cut → mvp
New PRD → prd-template → Linear spec + writing-plans
Phase modules: planning.md · research.md · implementation.md · testing.md · shipping.md
Per-task testing (mandatory)
Every task in docs/plan/tasks/*.md and every Linear step A–E must include a Test block
before the next task starts. No batching tests to the end of Phase 3.
| Phase | Testing duty |
|---|
| 1 Plan | Each AC → test type; each Linear step → proof command |
| 3 Implement | After each task: run its Vitest/smoke/verify command → PASS → next task |
| 4 Test | Full matrix + aggregate gates (testing-matrix) |
Contract: references/per-task-testing.md · authoring: gen-test
Five phases
Linear issues as agent prompts
Treat every executable issue as a prompt to Cursor/Claude: role, context, constraints, examples, chain (A–E steps), and eval (proof commands).
Full guide: references/linear-prompt-engineering.md · wireframes/wiring detail: planning.md
| Must have | Why |
|---|
| Problem statement + user story | Context — most-skipped, highest agent failure rate |
| Skills: line + domain SKILL.md read | Best practices per stack (mastra, supabase, …) |
| Good/bad Examples (security/AI) or wireframe + states (UI) | Multishot — reduces wrong-path implementations |
| Do NOT + out of scope | Negative prompting — stops scope creep and antipatterns |
proof: on every A–E step | Eval hook — done vs not done is measurable |
| No OR in security AC | Clarity — agents pick the easier (wrong) path |
blockedBy matches cross-issue AC | Relations mirror dependencies |
SSOT: edit docs/linear/issues/IPI-*.md first → node scripts/linear-update-issue.mjs IPI-NNN.
Slash commands (use these first)
| Command | When |
|---|
/task IPI-NNN | Full lifecycle — see flow at top |
/worktree | Audit / add / clean worktrees |
/audit [scope] | Forensic audit before shipping |
/supa [scope] | Supabase schema, RLS, migration, type-drift |
/pr-fix PR# | Fix PR review comments, resolve threads, re-run verify |
Scripts (fallback)
| Script | When |
|---|
node scripts/linear-update-issue.mjs <id> | Push spec md → Linear description |
node scripts/linear-update-issue.mjs --all | Bulk sync all IPI-*.md → Linear |
Requires LINEAR_API_KEY in .env.local. Details: shipping.md
Verification gates
Route by changed paths — full matrix: pr-workflow verify-matrix. Never run operator verify at repo root.
| Changed | Minimum |
|---|
app/** | cd app && npm run lint && npm run typecheck && npm test · npm run build if routes/config/env/middleware |
supabase/** | infisical run -- npm run supabase:verify · infisical run -- npm run supabase:verify-rls (+ edge/BI per matrix) |
Legacy src/** | infisical run -- npm run build && npm run test |
After DB changes: /supa or matrix scripts above.
Done gate
Never mark Done unless all of the following are true:
[ ] AC checked [x] in docs/linear/issues/IPI-*.md
[ ] Verify matrix green ([pr-workflow verify-matrix](../pr-workflow/references/verify-matrix.md))
[ ] task-verifier report exists or is explicitly waived (trivial typo only)
[ ] PR merged or user explicitly waived PR
[ ] tasks/plan/todo.md row updated 🟢
[ ] Linear marked Done (MCP or agreed fallback)
[ ] GitHub review threads resolved (if PR was opened)
Phase sequencing
| Skip | When |
|---|
| Phase 1 | Issue has A–E + Skills: line + prompt lint passed + spec md synced to Linear — not merely "steps exist" |
| Phase 2 | ≤3 files, no Supabase/RLS/edge/Mastra |
| Phase 4 | Never on auth/RLS/edge/Mastra/AI |
| Phase 5 | Never |
Check tasks/plan/todo.md for P0 dependencies before starting any IPI task.
Quick links
Contract
- One concern per PR and per commit — never mix docs+code or two IPI issues (pr-workflow)
- Remote Supabase only · no client secrets
- Traceability: IPI ↔ SPEC ↔
tasks/plan/todo.md ↔ code
- No push without user ask · never push to
main
