From 8ebd8770f1a7385b1b5c58138b082e5d5afe2947 Mon Sep 17 00:00:00 2001 From: shadowdevcode Date: Wed, 1 Apr 2026 16:06:45 +0530 Subject: [PATCH] docs: clarify Linear utility commands and sync modes across system docs - Add inline descriptions to all 4 Linear commands in CLAUDE.md and README.md - Replace numbered list with decision table in README Linear PM Layer section - Add inline comments to all Linear fields in project-state.md - Register linear-operations in CLAUDE.md knowledge index Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 10 +++++----- README.md | 21 +++++++++++---------- project-state.md | 24 +++++++++++++----------- 3 files changed, 29 insertions(+), 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 36b618c..6af0746 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,10 +37,10 @@ The system operates through sequential slash commands that activate specialized - `/explain` - Targeted learning session: understand a concept, pattern, or error via 80/20 rule - `/eval` - Score a completed issue's pipeline output against its spec using assertion-based grading - `/assign-reviewers` - Risk-based PR reviewer routing (standalone utility, no pipeline role) -- `/linear-bind` - Bind the active repo issue to a Linear team and project -- `/linear-sync` - Sync repo artifacts and workflow state into Linear -- `/linear-brief` - Read the current Linear view for the active issue -- `/linear-close` - Close the Linear project after repo workflow completion +- `/linear-bind` - Bind the active repo issue to a Linear team and project; run once after `/create-issue` (now automatic at end of `/create-issue`) +- `/linear-sync` - Mirror repo artifacts into Linear; accepts a mode: `issue` (brief), `plan` (PRD + child tasks), `status` (gate updates), `release` (deploy links) +- `/linear-brief` - Read-only summary of the current Linear issue/project state; use before standup or planning reviews +- `/linear-close` - Finalize and archive the Linear project after `/learning` completes ### Quality Gate System @@ -70,7 +70,7 @@ The system operates through sequential slash commands that activate specialized - Load **only** the files listed in the command's `## Required Knowledge` section (at the top of each `commands/*.md` file) - Do NOT load all 9 knowledge files for every command — each command specifies exactly what it needs - Only `/learning` loads the full knowledge base - - Full index for reference: product-principles, coding-standards, architecture-guide, ui-standards, analytics-framework, prompt-library, engineering-lessons, product-lessons, ai-model-guide + - Full index for reference: product-principles, coding-standards, architecture-guide, ui-standards, analytics-framework, prompt-library, engineering-lessons, product-lessons, ai-model-guide, linear-operations (loaded only by Linear commands) 5. **Load app context** (for engineering commands `/execute-plan`, `/deslop`, `/review`, `/peer-review`, `/qa-test`, `/docs`): - `apps//CODEBASE-CONTEXT.md` (if exists) diff --git a/README.md b/README.md index 7ba928b..5cede02 100644 --- a/README.md +++ b/README.md @@ -67,10 +67,10 @@ The OS enforces a sequential pipeline with quality gates. A stage cannot start u - `/docs` — Generate `CODEBASE-CONTEXT.md` for the active app - `/explain` — Deep-dive on a concept, pattern, or error -- `/linear-bind` — Bind the active repo issue to a Linear team/project -- `/linear-sync` — Sync repo artifacts and workflow status into Linear -- `/linear-brief` — Summarize the current Linear state for the active issue -- `/linear-close` — Close the Linear project after the repo workflow completes +- `/linear-bind` — Bind the active repo issue to a Linear team/project (auto-runs at end of `/create-issue`) +- `/linear-sync [mode]` — Mirror repo artifacts into Linear; modes: `issue`, `plan`, `status`, `release` +- `/linear-brief` — Read-only summary of the current Linear state; use before reviews or standups +- `/linear-close` — Finalize and archive the Linear project after `/learning` --- @@ -110,12 +110,13 @@ Linear exists to improve: Recommended usage: -1. Run `/linear-bind` after `/create-issue` -2. Run `/linear-sync issue` after the issue brief exists -3. Run `/linear-sync plan` after `/create-plan` to publish plan artifacts and child tasks -4. Run `/linear-sync status` after review gates to reflect blockers or approvals -5. Run `/linear-sync release` after `/deploy-check` -6. Run `/linear-close` after `/learning` +| Pipeline stage | Linear command | What it does | +| ------------------------------------- | -------------------------- | ------------------------------------------ | +| `/create-issue` | (auto) bind + `sync issue` | Creates Linear project; syncs issue brief | +| `/create-plan` | `/linear-sync plan` | Publishes PRD summary + child tasks | +| `/review`, `/peer-review`, `/qa-test` | `/linear-sync status` | Reflects gate pass/fail, surfaces blockers | +| `/deploy-check` | `/linear-sync release` | Attaches PR link and release notes | +| `/learning` | `/linear-close` | Marks project complete, archives it | If Linear is unavailable, the Linear utility command should fail explicitly. The 12-step pipeline remains usable because Linear is not the workflow engine. diff --git a/project-state.md b/project-state.md index aeb100c..c7a9cbe 100644 --- a/project-state.md +++ b/project-state.md @@ -127,18 +127,20 @@ ## Links -- linear_enabled: true -- linear_team_id: 70aea0d1-a706-481f-a0b7-3e636709ba77 + + +- linear_enabled: true +- linear_team_id: 70aea0d1-a706-481f-a0b7-3e636709ba77 - linear_team: Vijaypmworkspace -- linear_project_id: -- linear_project: -- linear_project_url: -- linear_root_issue_id: -- linear_root_issue_identifier: -- linear_cycle: -- linear_sync_map_path: -- linear_last_sync: 2026-04-01T07:41:00.000Z -- linear_sync_status: retroactive-sync-complete — issues 002–006 + 008 synced to Linear (Done). Sync maps written to experiments/linear-sync/. Issue 007 skipped (exploration-only, no sprint). +- linear_project_id: +- linear_project: +- linear_project_url: +- linear_root_issue_id: +- linear_root_issue_identifier: +- linear_cycle: +- linear_sync_map_path: +- linear_last_sync: 2026-04-01T07:41:00.000Z +- linear_sync_status: retroactive-sync-complete — issues 002–006 + 008 synced to Linear (Done). Sync maps written to experiments/linear-sync/. Issue 007 skipped (exploration-only, no sprint). - docs_home: experiments/ideas/issue-007.md - demo: - analytics_dashboard: