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

feat(workflow): add linear utility commands and workflow docs

Author: shadowdevcode

.claude/commands/linear-bind.md

@@ -0,0 +1,4 @@
+Read and execute the full command protocol from commands/linear-bind.md.
+This is a utility command — it can run anytime, outside the sequential pipeline.
+Read project-state.md and the active issue before executing.
+Activate the Linear Agent from agents/linear-agent.md.

.claude/commands/linear-brief.md

@@ -0,0 +1,4 @@
+Read and execute the full command protocol from commands/linear-brief.md.
+This is a utility command — it can run anytime, outside the sequential pipeline.
+Read project-state.md and the current Linear binding before executing.
+Activate the Linear Agent from agents/linear-agent.md.

.claude/commands/linear-close.md

@@ -0,0 +1,4 @@
+Read and execute the full command protocol from commands/linear-close.md.
+This is a utility command — it can run anytime, outside the sequential pipeline.
+Read project-state.md, the active issue, and closeout artifacts before executing.
+Activate the Linear Agent from agents/linear-agent.md.

.claude/commands/linear-sync.md

@@ -0,0 +1,4 @@
+Read and execute the full command protocol from commands/linear-sync.md.
+This is a utility command — it can run anytime, outside the sequential pipeline.
+Read project-state.md, the active issue, and relevant artifacts for the selected sync mode before executing.
+Activate the Linear Agent from agents/linear-agent.md.

.github/workflows/pr-auto-review.yml

@@ -33,4 +33,4 @@ jobs:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
         run: |
           claude --dangerously-skip-permissions \
-            -p "/assign-reviewers ${{ github.event.pull_request.html_url }}"
+            -p "Read commands/assign-reviewers.md and execute the full protocol for this PR: ${{ github.event.pull_request.html_url }}"

AGENTS.md

@@ -28,9 +28,10 @@ Each agent has a dedicated definition file in `/agents/` with full role instruct
 
 ## Utility Agents
 
-| Agent         | Role                                                | Definition                            |
-| ------------- | --------------------------------------------------- | ------------------------------------- |
-| Documentation | Maintains clear documentation (CODEBASE-CONTEXT.md) | [docs-agent.md](agents/docs-agent.md) |
+| Agent         | Role                                                | Definition                                |
+| ------------- | --------------------------------------------------- | ----------------------------------------- |
+| Documentation | Maintains clear documentation (CODEBASE-CONTEXT.md) | [docs-agent.md](agents/docs-agent.md)     |
+| Linear        | Syncs repo workflow state into Linear for PM use    | [linear-agent.md](agents/linear-agent.md) |
 
 ---
 

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2026-04-01 — Linear PM Layer (Retroactive Sync + Auto-Bind)
+
+**What:** Full Linear integration layer added as a PM-facing workflow mirror. The repo remains the source of truth; Linear reflects state for stakeholder visibility.
+
+- Created `commands/linear-bind.md` — binds active repo issue to a Linear team and project; creates `experiments/linear-sync/issue-<NNN>.json` sync map; writes `linear_enabled: true` and all binding fields to `project-state.md`
+- Created `commands/linear-sync.md` — mirrors repo artifacts into Linear in 4 modes: `issue` (brief), `plan` (document snapshot + child issues from manifest), `status` (stage labels + blockers), `release` (PR/deployment links)
+- Created `commands/linear-brief.md` — read-only summary of current Linear view; compares repo stage against Linear status; identifies mismatches
+- Created `commands/linear-close.md` — finalizes Linear project after `/learning`; sets project to `completed`, root issue to `Done`, creates closeout snapshot document
+- Created `agents/linear-agent.md` — Linear Agent role definition (product operations specialist); idempotent sync behavior; repo-as-source-of-truth constraint
+- Created `knowledge/linear-operations.md` — shared runtime rules: sync map schema, naming conventions, label taxonomy (`AI Product OS` parent + 7 children), status mapping, failure policy
+- Registered all 4 commands as `.claude/commands/` stubs
+- Added Linear PM Layer section to `CLAUDE.md` with recommended sync checkpoints
+- Updated `commands/create-issue.md` to auto-bind Linear at the end of every new issue creation (no manual `/linear-bind` step required going forward)
+- Retroactively synced issues 002–006 and 008 to Linear as `Completed`
+
+**Why:** Pipeline had no PM-facing visibility layer. Issues were built, shipped, and archived with zero Linear record. Linear now mirrors all 6 completed projects with closeout snapshots, enabling portfolio visibility and cycle velocity tracking.
+
+**Pipeline isolation:** Linear commands are utility-only. They do not alter stage progression, do not interact with `experiments/` artifact content, and cannot block or unblock pipeline stages.
+
+**Files:** `commands/linear-bind.md` (new), `commands/linear-sync.md` (new), `commands/linear-brief.md` (new), `commands/linear-close.md` (new), `agents/linear-agent.md` (new), `knowledge/linear-operations.md` (new), `.claude/commands/linear-*.md` (4 new stubs), `CLAUDE.md` (updated), `commands/create-issue.md` (updated), `experiments/linear-sync/issue-{002,003,004,005,006,008}.json` (new)
+
+---
+
 ## 2026-03-31 — Assign PR Reviewers (Automated Risk-Based Review Routing)
 
 **What:** New standalone utility command `/assign-reviewers` that assesses PR risk from the actual code diff and routes accordingly.

CLAUDE.md

@@ -37,6 +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
 
 ### Quality Gate System
 
@@ -70,6 +74,28 @@ The system operates through sequential slash commands that activate specialized
 5. **Load app context** (for engineering commands `/execute-plan`, `/deslop`, `/review`, `/peer-review`, `/qa-test`, `/docs`):
    - `apps/<project_name>/CODEBASE-CONTEXT.md` (if exists)
 
+### Linear PM Layer
+
+Linear is optional and PM-facing only.
+
+Rules:
+
+- The repo remains the source of truth
+- `project-state.md` remains canonical for workflow state
+- `experiments/linear-sync/issue-<NNN>.json` stores durable Linear ids for idempotent re-syncs
+- Linear utility commands may read and write Linear only after reading repo state
+- Linear commands must never silently skip failed writes
+- Existing pipeline commands remain valid even if Linear is unavailable
+
+Recommended checkpoints:
+
+- **`/create-issue` auto-binds Linear** — `/linear-bind` + root issue creation run automatically at the end of every `/create-issue`. No manual bind step required.
+- After `/create-issue`: `/linear-sync issue` (brief already bound; sync the description)
+- After `/create-plan`: `/linear-sync plan`
+- After `/review`, `/peer-review`, `/qa-test`: `/linear-sync status`
+- After `/deploy-check`: `/linear-sync release`
+- After `/learning`: `/linear-close`
+
 **Never use hard-coded template examples.** All outputs must reference the active project context.
 
 ### State Management
@@ -82,6 +108,13 @@ After every command execution, update `project-state.md`:
 - Set quality gate status (pass/fail) for review stages
 - Append key decisions to the Decisions Log
 
+For Linear utility commands:
+
+- Update only the Linear metadata fields
+- Persist durable Linear ids in `experiments/linear-sync/issue-<NNN>.json`
+- Never change pipeline stage progression as a side effect of a Linear command
+- Record explicit sync failures instead of silently ignoring them
+
 **Blocked State Rule**: If a quality gate fails, set `status` to `blocked` and add the blocker to the Blockers section. Do not proceed until resolved.
 
 ---

README.md

@@ -67,6 +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
 
 ---
 
@@ -85,6 +89,38 @@ Every agent reads the knowledge base before executing — preventing the same cl
 
 ---
 
+## Linear PM Layer
+
+Linear is an optional PM-facing layer on top of the repo workflow.
+
+The source of truth remains in this repository:
+
+- `project-state.md` is the canonical workflow state
+- `experiments/` contains the canonical issue, exploration, plan, and result artifacts
+- `experiments/linear-sync/` stores durable Linear sync identities per issue
+- `commands/` defines the execution contracts
+
+Linear exists to improve:
+
+- prioritization
+- roadmap visibility
+- blocker communication
+- task tracking from execution manifests
+- release and closeout visibility
+
+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`
+
+If Linear is unavailable, the Linear utility command should fail explicitly. The 12-step pipeline remains usable because Linear is not the workflow engine.
+
+---
+
 ## Getting Started (Forking This Repo)
 
 1. **Check the current state** — read [`project-state.md`](project-state.md) to see what stage the system is at and which issue is active

agents/linear-agent.md

@@ -0,0 +1,133 @@
+# Linear Agent
+
+Role:
+You are a product operations specialist responsible for keeping Linear aligned with the AI Product OS.
+
+Your job is to reflect the repo's workflow state into Linear without changing the repo's role as the source of truth.
+
+You think like:
+
+product operations manager
+program manager
+technical chief of staff
+
+Your priority is workflow clarity, idempotent sync behavior, and accurate status communication.
+
+---
+
+# Responsibilities
+
+1 Bind the active repo issue to a Linear team and project
+2 Sync repo artifacts into Linear issues, projects, and comments
+3 Reflect blocked states and quality gate outcomes in Linear
+4 Attach execution artifacts such as plan docs, manifests, PRs, and postmortems
+5 Close Linear work cleanly after the repo workflow completes
+
+You must never invent product direction, scope changes, or engineering decisions.
+
+---
+
+# Inputs
+
+You will receive:
+
+project-state.md
+issue brief
+exploration output
+plan output
+manifest JSON
+quality gate results
+deployment links
+postmortem artifacts
+
+---
+
+# Process
+
+Follow this sequence.
+
+---
+
+## 1 Resolve Repo Context
+
+Read the active repo issue and determine:
+
+issue number
+project name
+current stage
+status
+relevant artifact links
+
+If required repo context is missing, raise an explicit error.
+
+---
+
+## 2 Resolve Linear Target
+
+Determine the destination:
+
+team
+project
+cycle if provided
+existing issue or child issues if already synced
+
+Never create duplicates when an existing Linear object can be updated.
+
+---
+
+## 3 Upsert Linear State
+
+Create or update only the objects required by the requested command.
+
+Examples:
+
+bind active issue to project
+create child issues from manifest tasks
+post blocker summaries after failed quality gates
+attach release links after deploy-check
+
+---
+
+## 4 Preserve Source Of Truth
+
+The repo remains canonical.
+
+Rules:
+
+- Never treat Linear as authoritative over repo files
+- Never overwrite repo intent based on Linear edits alone
+- Never silently skip a failed Linear write
+
+If Linear is unavailable, raise an explicit error with operation context.
+
+---
+
+# Output Format
+
+Return output using this structure.
+
+---
+
+Operation
+
+Repo Context
+
+Linear Target
+
+Actions Taken
+
+Sync Result
+
+Next Recommended Command
+
+---
+
+# Rules
+
+Be idempotent.
+
+Prefer updates over creation.
+
+Use repo issue numbers as the stable foreign key across systems.
+
+Do not add workflow steps to the 12-stage pipeline.