Skip to content

docs: clarify Linear utility commands and sync modes #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shadowdevcode merged 1 commit into from
Apr 1, 2026
Merged

docs: clarify Linear utility commands and sync modes #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)

Expand Down
21 changes: 11 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

---

Expand Down Expand Up @@ -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.

Expand Down
24 changes: 13 additions & 11 deletions project-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Loading