Merge pull request #13 from shadowdevcode/feat/linear-workflow-sync

docs: clarify Linear utility commands and sync modes

Author: shadowdevcode

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/<project_name>/CODEBASE-CONTEXT.md` (if exists)
 

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.
 

project-state.md

@@ -127,18 +127,20 @@
 
 ## Links
 
-- linear_enabled: true
-- linear_team_id: 70aea0d1-a706-481f-a0b7-3e636709ba77
+<!-- Linear fields: set by /linear-bind; updated by /linear-sync; read by /linear-brief; cleared on /linear-close -->
+
+- linear_enabled: true <!-- set to true by /linear-bind; false = Linear layer inactive -->
+- linear_team_id: 70aea0d1-a706-481f-a0b7-3e636709ba77 <!-- immutable after bind -->
 - 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: <!-- populated by /linear-bind when project is created -->
+- linear_project: <!-- human-readable project name in Linear -->
+- linear_project_url: <!-- direct link to the Linear project page -->
+- linear_root_issue_id: <!-- id of the root issue created in Linear -->
+- linear_root_issue_identifier: <!-- e.g. VIJ-42 — display identifier for the root issue -->
+- linear_cycle: <!-- Linear cycle/sprint, if assigned -->
+- linear_sync_map_path: <!-- path to experiments/linear-sync/issue-NNN.json (durable id map) -->
+- linear_last_sync: 2026-04-01T07:41:00.000Z <!-- ISO timestamp of last successful /linear-sync -->
+- 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). <!-- last sync mode or failure reason -->
 - docs_home: experiments/ideas/issue-007.md
 - demo:
 - analytics_dashboard: