diff --git a/.claude/commands/linear-bind.md b/.claude/commands/linear-bind.md new file mode 100644 index 0000000..2277d3e --- /dev/null +++ b/.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. diff --git a/.claude/commands/linear-brief.md b/.claude/commands/linear-brief.md new file mode 100644 index 0000000..f05266e --- /dev/null +++ b/.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. diff --git a/.claude/commands/linear-close.md b/.claude/commands/linear-close.md new file mode 100644 index 0000000..8961611 --- /dev/null +++ b/.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. diff --git a/.claude/commands/linear-sync.md b/.claude/commands/linear-sync.md new file mode 100644 index 0000000..08f4657 --- /dev/null +++ b/.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. diff --git a/.github/workflows/pr-auto-review.yml b/.github/workflows/pr-auto-review.yml index faf8dc2..82a47fe 100644 --- a/.github/workflows/pr-auto-review.yml +++ b/.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 }}" diff --git a/AGENTS.md b/AGENTS.md index ad8e949..e6548b5 100644 --- a/AGENTS.md +++ b/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) | --- diff --git a/CHANGELOG.md b/CHANGELOG.md index dbb986f..d12aa0f 100644 --- a/CHANGELOG.md +++ b/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-.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. diff --git a/CLAUDE.md b/CLAUDE.md index 93a6a3e..36b618c 100644 --- a/CLAUDE.md +++ b/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//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-.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-.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. --- diff --git a/README.md b/README.md index d82efad..7ba928b 100644 --- a/README.md +++ b/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 diff --git a/agents/linear-agent.md b/agents/linear-agent.md new file mode 100644 index 0000000..afb25af --- /dev/null +++ b/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. diff --git a/command-protocol.md b/command-protocol.md index 1249d83..396c013 100644 --- a/command-protocol.md +++ b/command-protocol.md @@ -90,6 +90,10 @@ Utility Commands (run anytime, outside the sequential pipeline): docs — Generate AI-native CODEBASE-CONTEXT.md for the active app explain — Targeted PM learning session via 80/20 rule eval — Score a completed issue's pipeline output against its spec using assertion-based grading +linear-bind — Bind the active repo issue to a Linear team/project +linear-sync — Sync repo artifacts and workflow state into Linear +linear-brief — Summarize the current Linear view for the active issue +linear-close — Close the Linear project after repo workflow completion --- @@ -233,6 +237,29 @@ After /explain: - Does not update pipeline stage - No state change required +After /linear-bind: + +- Does not update pipeline stage +- Writes only Linear metadata fields in `project-state.md` +- Must not create duplicate Linear projects for the same active issue + +After /linear-sync: + +- Does not update pipeline stage +- Updates `linear_last_sync` and `linear_sync_status` +- Must upsert Linear objects instead of duplicating them + +After /linear-brief: + +- Does not update pipeline stage +- No state change required unless the command explicitly records a sync-health diagnostic + +After /linear-close: + +- Does not update pipeline stage +- Updates `linear_last_sync` and `linear_sync_status` +- Must not close a project unless repo completion is already recorded + ## New project rule When /create-issue is run with a new idea that differs from the current active project: @@ -248,6 +275,39 @@ Do not proceed to the next stage until the blocker is resolved and the gate is r --- +# Linear Sync Protocol + +Linear is an optional PM layer, not the workflow engine. + +Rules: + +1. Read repo state first. `project-state.md` and repo artifacts remain canonical. +2. Linear commands must never modify the 12-step pipeline stage progression. +3. Linear sync must be idempotent. Re-running the same sync should update existing Linear objects rather than create duplicates. +4. Use the repo issue number as the stable foreign key across systems. +5. Persist durable Linear ids in `experiments/linear-sync/issue-.json`. +6. Child Linear tasks should be derived from `manifest-.json` when available. +7. If Linear is unavailable, raise an explicit error with operation context. Do not silently skip. + +## Recommended Checkpoints + +- After `create-issue`: `linear-bind`, then `linear-sync issue` +- 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` + +## Default State Mapping + +- `create-issue`, `explore` -> discovery or triage +- `create-plan` -> planned +- `execute-plan`, `deslop` -> in progress +- blocked review stages -> blocked or at risk +- successful `deploy-check` -> release ready +- successful `learning` -> completed + +--- + # Command Execution Framework Every command in the AI Product OS must follow this execution order. diff --git a/commands/create-issue.md b/commands/create-issue.md index 8011b30..78fed81 100644 --- a/commands/create-issue.md +++ b/commands/create-issue.md @@ -94,6 +94,26 @@ Hypothesis --- +# Post-Output Steps + +After writing `experiments/ideas/issue-.md` and updating `project-state.md`: + +## Auto-Bind Linear + +Immediately run `/linear-bind` for the new issue. + +This ensures `linear_enabled: true` is set from the moment every issue is created — no manual bind step required. + +Expected outcome: + +- `experiments/linear-sync/issue-.json` created with team, project, and root issue ids +- `project-state.md` updated with `linear_enabled: true` and all linear binding fields +- Linear root issue created in `Backlog` with label `AI Product OS/Discovery` + +If Linear is unavailable, log the failure explicitly and continue — do not block the pipeline. + +--- + # Next Step -Send this issue to the Research Agent for validation. +Send this issue to the Research Agent for validation via `/explore`. diff --git a/commands/linear-bind.md b/commands/linear-bind.md new file mode 100644 index 0000000..b603a88 --- /dev/null +++ b/commands/linear-bind.md @@ -0,0 +1,171 @@ +# Command: /linear-bind + +## Required Knowledge + +Load only these knowledge files before executing: + +- knowledge/linear-operations.md + +--- + +Purpose: +Bind the active repo workflow to a Linear team and project. + +This command establishes the durable relationship between the current `active_issue` and its Linear representation. It does not change the 12-step pipeline. It only creates or updates the PM-facing tracking layer. + +--- + +# When to Run + +Run `/linear-bind` when: + +- a new active issue should be tracked in Linear +- the active issue already exists in the repo but has no Linear binding +- the Linear team or project name needs to be corrected + +Recommended checkpoint: + +- Immediately after `/create-issue` + +--- + +# Input + +Run as: + +```text +/linear-bind [team] [project-name] +``` + +If `team` is omitted and exactly one Linear team exists, use that team. If more than one team exists, raise an explicit error. + +If `project-name` is omitted, derive it from the repo issue title. + +--- + +# Context Loading + +1. Read `project-state.md` +2. Read `experiments/ideas/.md` +3. Read `experiments/exploration/exploration-.md` if it exists +4. Read `experiments/linear-sync/issue-.json` if it exists + +Required fields: + +- `active_issue` +- project name +- current stage + +If `active_issue` is `none`, stop and raise an explicit error. + +--- + +# Agent Activated + +Activate `agents/linear-agent.md`. + +--- + +# Execution + +## Step 1 — Resolve Binding Context + +Extract: + +- repo issue number +- repo issue title +- current stage +- existing Linear metadata from `project-state.md` +- existing sync map metadata from `experiments/linear-sync/issue-.json` + +## Step 2 — Resolve Linear Destination + +Using the provided team and optional project name, use these MCP tools: + +- `list_teams`, `get_team` +- `list_issue_labels`, `create_issue_label` +- `list_projects`, `save_project` +- `list_issues`, `save_issue` + +Rules: + +- resolve the team by explicit argument, or default to the sole team if exactly one exists +- ensure the parent label group `AI Product OS` exists +- ensure child labels exist: `Discovery`, `Planning`, `Execution`, `Review`, `Blocked`, `Release Ready`, `Completed` +- ensure one Linear project exists for the repo issue +- ensure one root Linear issue exists under that project + +Default object shape: + +- project title: `issue- — ` +- root issue title: `issue- — ` +- root issue labels: `Feature` and `AI Product OS/Discovery` +- root issue status: `Backlog` + +## Step 3 — Persist Binding Metadata + +Write the following fields to `project-state.md`: + +- `linear_enabled: true` +- `linear_team_id` +- `linear_team` +- `linear_project_id` +- `linear_project` +- `linear_project_url` +- `linear_root_issue_id` +- `linear_root_issue_identifier` +- `linear_sync_map_path` +- `linear_last_sync` +- `linear_sync_status` + +Also write `experiments/linear-sync/issue-.json` with: + +- team id and name +- project id, name, and URL +- root issue id, identifier, and title +- label ids +- empty `documents` object +- empty `tasks` object +- last sync mode `bind` + +Do not modify any pipeline stage fields. + +## Step 4 — Confirm Idempotency + +Lookup order: + +1. `experiments/linear-sync/issue-.json` +2. `project-state.md` +3. live Linear query by exact team plus exact title + +Re-running `/linear-bind` must update existing objects rather than create duplicates. + +--- + +# Failure Policy + +- If the Linear team cannot be resolved, raise an explicit error +- If no team argument is provided and multiple teams exist, raise an explicit error +- If the active issue is missing, raise an explicit error +- If Linear write operations fail, raise an explicit error with operation context +- Never silently continue without a binding + +--- + +# Output Format + +```text +Operation + +Repo Context + +Linear Team + +Linear Project + +Root Linear Issue + +Binding Result + +Updated State Fields +``` diff --git a/commands/linear-brief.md b/commands/linear-brief.md new file mode 100644 index 0000000..6bf7a72 --- /dev/null +++ b/commands/linear-brief.md @@ -0,0 +1,131 @@ +# Command: /linear-brief + +## Required Knowledge + +Load only these knowledge files before executing: + +- knowledge/linear-operations.md + +--- + +Purpose: +Read the current Linear view for the active repo issue and summarize it for the PM. + +This command is read-only from the repo's perspective. It helps the PM understand the current Linear representation without manually opening the tool. + +--- + +# When to Run + +Run `/linear-brief` when: + +- preparing for planning or status review +- checking child task progress against the manifest +- confirming blocker visibility before a release decision + +This command can run anytime after `/linear-bind`. + +--- + +# Input + +Run as: + +```text +/linear-brief [active|project|cycle] +``` + +Default mode: `active` + +--- + +# Context Loading + +1. Read `project-state.md` +2. Read the active issue file +3. Read the plan and manifest if they exist +4. Read Linear metadata from `project-state.md` +5. Read `experiments/linear-sync/issue-.json` if it exists + +If `linear_enabled` is not `true`, stop and raise an explicit error. + +--- + +# Agent Activated + +Activate `agents/linear-agent.md`. + +--- + +# Execution + +## Step 1 — Resolve View + +- `active` -> summarize the bound project and the active repo issue +- `project` -> summarize the full Linear project view and child issues +- `cycle` -> summarize the current cycle only if `linear_cycle` exists + +Resolve objects using this lookup order: + +1. `experiments/linear-sync/issue-.json` +2. `project-state.md` +3. live Linear query by exact team plus exact title + +## Step 2 — Read Linear State + +Use these MCP tools: + +- `get_project` +- `get_issue` +- `list_issues` + +Gather: + +- project name +- project status +- current cycle +- child issue progress +- open blockers +- attached links for plan, PR, deployment, and postmortem if present + +## Step 3 — Compare Against Repo State + +Highlight any mismatch between: + +- repo stage and Linear status +- manifest tasks and Linear child issues +- known blockers and Linear blocker visibility +- expected stage labels and current stage labels +- expected sync map identifiers and live Linear objects + +Do not mutate repo state. + +--- + +# Failure Policy + +- If the project is not bound, raise an explicit error +- If the requested view requires `linear_cycle` and it is missing, raise an explicit error +- If Linear read operations fail, raise an explicit error with view context + +--- + +# Output Format + +```text +Linear Brief + +Repo Stage + +Linear Status + +Child Task Summary + +Open Blockers + +Mismatches + +Sync Map Health + +Recommended Next PM Action +``` diff --git a/commands/linear-close.md b/commands/linear-close.md new file mode 100644 index 0000000..e4ce0e9 --- /dev/null +++ b/commands/linear-close.md @@ -0,0 +1,109 @@ +# Command: /linear-close + +## Required Knowledge + +Load only these knowledge files before executing: + +- knowledge/linear-operations.md + +--- + +Purpose: +Close the Linear project for the active issue after the repo workflow is complete. + +This command finalizes the PM-facing tracking layer after `/learning` has finished in the repo. + +--- + +# When to Run + +Run `/linear-close` after `/learning` succeeds. + +This command should not be used to bypass unfinished repo stages. + +--- + +# Context Loading + +1. Read `project-state.md` +2. Read `experiments/results/postmortem-.md` if it exists +3. Read the most recent learning outputs if they exist +4. Read Linear metadata from `project-state.md` +5. Read `experiments/linear-sync/issue-.json` if it exists + +If the active issue is not bound to Linear, stop and raise an explicit error. + +--- + +# Agent Activated + +Activate `agents/linear-agent.md`. + +--- + +# Execution + +## Step 1 — Verify Repo Completion + +Confirm: + +- `last_command_run` is `/learning` or equivalent completion is recorded +- repo status is `completed`, `done`, or otherwise clearly closed + +If the repo workflow is still active, raise an explicit error. + +## Step 2 — Finalize Linear Project + +Use these MCP tools: + +- `get_project`, `save_project` +- `get_issue`, `save_issue` +- `list_comments`, `save_comment` +- `create_document`, `update_document` + +Expected behavior: + +- set the project state to `completed` +- set the root issue status to `Done` +- remove active stage labels and apply `AI Product OS/Completed` +- create or update a closeout snapshot document titled `issue- Closeout Snapshot` +- include postmortem summary, learning summary, and local repo artifact paths +- add a final closeout comment on the root issue + +## Step 3 — Update Repo Metadata + +Write these fields to `project-state.md`: + +- `linear_last_sync` +- `linear_sync_status` + +Also update `experiments/linear-sync/issue-.json` with: + +- closeout document id +- last sync mode `close` +- last sync timestamp + +Do not modify historical pipeline records. + +--- + +# Failure Policy + +- If the repo workflow is not complete, raise an explicit error +- If closing the Linear project fails, raise an explicit error with target context + +--- + +# Output Format + +```text +Operation + +Repo Completion Check + +Linear Target + +Closeout Actions + +Final Sync Result +``` diff --git a/commands/linear-sync.md b/commands/linear-sync.md new file mode 100644 index 0000000..eb72b92 --- /dev/null +++ b/commands/linear-sync.md @@ -0,0 +1,199 @@ +# Command: /linear-sync + +## Required Knowledge + +Load only these knowledge files before executing: + +- knowledge/linear-operations.md + +--- + +Purpose: +Sync repo workflow artifacts into Linear without changing the repo's canonical role. + +This command mirrors the state already captured in repo files into the appropriate Linear project, issues, and comments. + +--- + +# When to Run + +Run `/linear-sync` after the repo artifact already exists. + +Recommended checkpoints: + +- After `/create-issue` -> `/linear-sync issue` +- After `/create-plan` -> `/linear-sync plan` +- After `/review`, `/peer-review`, `/qa-test` -> `/linear-sync status` +- After `/deploy-check` -> `/linear-sync release` + +--- + +# Input + +Run as: + +```text +/linear-sync +``` + +--- + +# Context Loading + +1. Read `project-state.md` +2. Read `experiments/ideas/.md` +3. Read `experiments/exploration/exploration-.md` if it exists +4. Read `experiments/plans/plan-.md` if it exists +5. Read `experiments/plans/manifest-.json` if it exists +6. Read relevant result artifacts from `experiments/results/` based on sync mode +7. Read `experiments/linear-sync/issue-.json` if it exists + +If `linear_enabled` is not `true`, stop and raise an explicit error instructing the PM to run `/linear-bind` first. + +--- + +# Agent Activated + +Activate `agents/linear-agent.md`. + +--- + +# Execution + +## Step 1 — Validate Binding + +Confirm the active issue has: + +- `linear_enabled: true` +- `linear_team` +- `linear_project` +- `linear_sync_map_path` + +Lookup order: + +1. `experiments/linear-sync/issue-.json` +2. `project-state.md` +3. live Linear query by exact team plus exact title + +If any field is missing, fail explicitly. + +## Step 2 — Resolve Sync Mode + +Use these MCP tools as needed: + +- `get_project`, `save_project` +- `get_issue`, `list_issues`, `save_issue` +- `list_comments`, `save_comment` +- `create_document`, `update_document` + +### `issue` + +Sync the opportunity brief into Linear. + +Expected behavior: + +- update the root Linear issue title and description from the repo issue brief +- include local repo artifact paths as plain text in the description +- ensure `AI Product OS/Discovery` is applied +- keep the root issue in `Backlog` + +### `plan` + +Sync planning artifacts. + +Expected behavior: + +- create or update the Linear project +- set the project state to `planned` +- create or update a Linear document snapshot titled `issue- Plan Snapshot` +- include plan summary, manifest summary, and local repo paths for the plan and manifest +- create or update child issues from `manifest-.json` +- child issue title format: `[issue-][] ` +- child issue description must include phase id, phase name, assigned agent, files to create, files to modify, verification command, and test file +- child issues default to status `Todo` and labels `Feature` plus `AI Product OS/Execution` +- use manifest task IDs plus the sync map as stable identifiers to avoid duplicates +- if the manifest file is missing, raise an explicit error + +### `status` + +Sync workflow status and blockers. + +Expected behavior: + +- map repo stage and status into Linear project status +- update the root issue stage label based on repo stage: + - `create-issue`, `explore` -> `Discovery` + - `create-plan` -> `Planning` + - `execute-plan`, `deslop` -> `Execution` + - `review`, `peer-review`, `qa-test` -> `Review` +- add `Blocked` if repo status is blocked +- add `Release Ready` after successful `deploy-check` +- add comments summarizing review, peer-review, or QA outcomes +- if blocked, include blocker details from `project-state.md` or the relevant result file +- keep child issues unchanged in v1 + +### `release` + +Sync deployment readiness. + +Expected behavior: + +- attach PR URL and deployment links as real Linear links on the root issue +- add a release summary comment +- apply `AI Product OS/Release Ready` +- keep the root issue in `In Review` until `/linear-close` + +## Step 3 — Update Sync Metadata + +Write these fields back to `project-state.md`: + +- `linear_last_sync` +- `linear_sync_status` + +Also update `experiments/linear-sync/issue-.json` with: + +- last sync mode +- last sync timestamp +- document ids created or updated +- task issue mappings created or updated + +Do not alter repo stage progression. + +--- + +# State Mapping + +- `create-issue` and `explore` -> `Backlog` +- `create-plan` -> planned +- `execute-plan` and `deslop` -> `In Progress` +- blocked review stages -> `In Review` plus `Blocked` +- successful `deploy-check` -> `In Review` plus `Release Ready` + +--- + +# Failure Policy + +- If a required repo artifact for the selected mode is missing, raise an explicit error +- If a Linear write fails, raise an explicit error with mode and target context +- If label or document creation conflicts, recover by lookup instead of duplicating objects +- Never create duplicates when an object with the same repo issue number or manifest task ID already exists + +--- + +# Output Format + +```text +Mode + +Repo Context + +Linear Target + +Objects Created + +Objects Updated + +Updated Sync Map + +Sync Result +``` diff --git a/commands/peer-review.md b/commands/peer-review.md index 4efe2b5..7795d28 100644 --- a/commands/peer-review.md +++ b/commands/peer-review.md @@ -24,6 +24,8 @@ You are responsible for performing a deep system review from a principal enginee You must challenge assumptions and identify weaknesses that may not appear in normal code review. +Adopt three distinct review lenses in sequence. Each lens has a different focus and produces its own findings section. This approximates having multiple specialized reviewers: a CTO (architecture), a reliability engineer (edge cases/security), and a product lead (PM alignment). + --- # Input @@ -40,86 +42,100 @@ System Architecture # Process -Follow this sequence. +Follow this sequence. Complete each lens fully before moving to the next. --- -## 1 Architecture Evaluation +## Lens 1 — Architecture & Scalability (CTO Perspective) + +Think like a principal engineer evaluating long-term system health. -Assess whether the architecture is appropriate for the product. +Assess: -Identify: +- Is the architecture appropriate for the product's scope and user volume? +- Are there unnecessary abstractions or missing system components? +- How does the system behave under growth (high user volume, heavy AI load, large datasets)? +- Are there fragile design patterns that will break under real-world conditions? -unnecessary complexity -missing system components -fragile design patterns +Flag: unnecessary complexity, missing components, scalability ceilings, fragile patterns. --- -## 2 Scalability Analysis +## Lens 2 — Edge Cases, Security & Reliability (Reliability Engineer Perspective) -Analyze how the system behaves under growth. +Think like an engineer who has been paged at 3am because of this system. -Examples: +Assess: -high user volume -heavy AI processing load -large datasets +- What are the real-world failure scenarios (partial service failure, AI errors, network interruptions)? +- Are there single points of failure, missing retries, or poor error handling? +- Are there security risks: unprotected endpoints, exposed secrets, injection vectors, missing auth? +- Are there race conditions, partial-failure states, or data corruption paths? + +Flag: reliability risks, security gaps, missing error handling, untested failure modes. --- -## 3 Edge Case Analysis +## Lens 3 — Product Coherence & PM Alignment (Product Lead Perspective) + +Think like a PM reading the implementation against the original spec. -Identify real-world failure scenarios. +Assess: -Examples: +- Does the implementation solve the user problem stated in the issue brief? +- Are there product decisions in the code that contradict the spec or architectural plan? +- Are there UX flows that are technically correct but will confuse or frustrate users? +- Is telemetry wired correctly to measure the North Star metric? -partial service failure -AI processing errors -network interruptions +Flag: spec drift, UX friction points, missing or mis-wired telemetry, scope creep. --- -## 4 Reliability Risks +# Verdict -Identify risks such as: +After all three lenses, produce a combined verdict: -single points of failure -missing retries -poor error handling +- APPROVED — no blocking issues across all lenses +- BLOCKED — one or more blocking issues found; list each with lens source --- -## 5 Product Alignment - -Verify the system still solves the intended user problem. +# Output Format -Confirm implementation aligns with product goals. +Return output using this structure. --- -# Output Format +Lens 1: Architecture & Scalability -Return output using this structure. +[findings or "No blocking issues"] --- -Architecture Concerns +Lens 2: Edge Cases, Security & Reliability + +[findings or "No blocking issues"] -Scalability Risks +--- -Edge Cases +Lens 3: Product Coherence & PM Alignment -Reliability Risks +[findings or "No blocking issues"] -Product Alignment Issues +--- -Recommendations +Verdict: APPROVED / BLOCKED + +[If BLOCKED: list each blocking issue with its lens label, severity, and required fix] --- # Rules +Complete all three lenses — do not skip a lens because the previous one found issues. + +Each lens must produce an independent assessment, not a repeat of prior findings. + Challenge assumptions. Focus on real-world system reliability. diff --git a/experiments/linear-sync/.gitkeep b/experiments/linear-sync/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/experiments/linear-sync/.gitkeep @@ -0,0 +1 @@ + diff --git a/experiments/linear-sync/issue-002.json b/experiments/linear-sync/issue-002.json new file mode 100644 index 0000000..2931ac1 --- /dev/null +++ b/experiments/linear-sync/issue-002.json @@ -0,0 +1,20 @@ +{ + "issue_number": "002", + "issue_title": "Gmail Summary to WhatsApp Notifier", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "253a9894-fd58-43ac-aa31-9f5a82632100", + "project_name": "issue-002 — Gmail Summary to WhatsApp Notifier", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-002-gmail-summary-to-whatsapp-notifier-8eacbcad1661", + "root_issue_id": "VIJ-5", + "root_issue_identifier": "VIJ-5", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-5/issue-002-gmail-summary-to-whatsapp-notifier", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:24:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-07" +} diff --git a/experiments/linear-sync/issue-003.json b/experiments/linear-sync/issue-003.json new file mode 100644 index 0000000..98004fe --- /dev/null +++ b/experiments/linear-sync/issue-003.json @@ -0,0 +1,20 @@ +{ + "issue_number": "003", + "issue_title": "AI Personal Finance Advisor for Young Earners", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "0a85110d-8e42-4268-9428-b798e994adbf", + "project_name": "issue-003 — AI Personal Finance Advisor", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-003-ai-personal-finance-advisor-8bf0ffb7b328", + "root_issue_id": "VIJ-6", + "root_issue_identifier": "VIJ-6", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-6/issue-003-ai-personal-finance-advisor", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:39:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-08" +} diff --git a/experiments/linear-sync/issue-004.json b/experiments/linear-sync/issue-004.json new file mode 100644 index 0000000..c3da80b --- /dev/null +++ b/experiments/linear-sync/issue-004.json @@ -0,0 +1,20 @@ +{ + "issue_number": "004", + "issue_title": "To-Do List for Product Managers (Project Clarity)", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "e11a70a6-3281-46f2-96d7-7e32cbfc53b1", + "project_name": "issue-004 — Project Clarity (PM To-Do List)", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-004-project-clarity-pm-to-do-list-9d2090312ee5", + "root_issue_id": "VIJ-7", + "root_issue_identifier": "VIJ-7", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-7/issue-004-project-clarity-pm-to-do-list", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:39:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-11" +} diff --git a/experiments/linear-sync/issue-005.json b/experiments/linear-sync/issue-005.json new file mode 100644 index 0000000..d9e4202 --- /dev/null +++ b/experiments/linear-sync/issue-005.json @@ -0,0 +1,20 @@ +{ + "issue_number": "005", + "issue_title": "SMB Feature Bundling Engine", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "2601fb6a-c01f-4ac0-aa95-ee19d053d061", + "project_name": "issue-005 — SMB Feature Bundling Engine", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-005-smb-feature-bundling-engine-2c6a697b2b36", + "root_issue_id": "VIJ-8", + "root_issue_identifier": "VIJ-8", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-8/issue-005-smb-feature-bundling-engine", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:40:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-14" +} diff --git a/experiments/linear-sync/issue-006.json b/experiments/linear-sync/issue-006.json new file mode 100644 index 0000000..e8a6377 --- /dev/null +++ b/experiments/linear-sync/issue-006.json @@ -0,0 +1,20 @@ +{ + "issue_number": "006", + "issue_title": "Ozi Reorder Experiment — Improving Repeat Purchase for Baby Essentials", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "3274f9dc-6bdf-444b-bcb6-2a5f0cb677f3", + "project_name": "issue-006 — Ozi Reorder Experiment", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-006-ozi-reorder-experiment-d2ed6d95201e", + "root_issue_id": "VIJ-9", + "root_issue_identifier": "VIJ-9", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-9/issue-006-ozi-reorder-experiment", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:40:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-20" +} diff --git a/experiments/linear-sync/issue-008.json b/experiments/linear-sync/issue-008.json new file mode 100644 index 0000000..5ab9f69 --- /dev/null +++ b/experiments/linear-sync/issue-008.json @@ -0,0 +1,20 @@ +{ + "issue_number": "008", + "issue_title": "Hyper-Personalized Style Concierge — Nykaa Fashion Discovery Feed", + "team_id": "70aea0d1-a706-481f-a0b7-3e636709ba77", + "team_name": "Vijaypmworkspace", + "project_id": "0badbc77-c0c8-4f21-be5a-3ec292940b73", + "project_name": "issue-008 — Nykaa Fashion Style Concierge", + "project_url": "https://linear.app/vijaypmworkspace/project/issue-008-nykaa-fashion-style-concierge-881b9db55f72", + "root_issue_id": "VIJ-10", + "root_issue_identifier": "VIJ-10", + "root_issue_url": "https://linear.app/vijaypmworkspace/issue/VIJ-10/issue-008-nykaa-fashion-style-concierge", + "labels": { + "feature": "70095fc1-871c-427e-bc1f-2c29b8d87aa8", + "completed": "3d396021-0cab-46d0-8320-c10ddd72af6d" + }, + "last_sync_mode": "close", + "last_sync_timestamp": "2026-04-01T07:40:00.000Z", + "pipeline_status": "completed", + "learning_date": "2026-03-31" +} diff --git a/knowledge/linear-operations.md b/knowledge/linear-operations.md new file mode 100644 index 0000000..7321bec --- /dev/null +++ b/knowledge/linear-operations.md @@ -0,0 +1,183 @@ +# Linear Operations + +Shared runtime rules for the Linear utility commands. + +These rules define how the AI Product OS uses Linear as a PM-facing layer while keeping the repo as the source of truth. + +--- + +## Source Of Truth + +- The repo is canonical. +- `project-state.md` is the human-readable workflow state. +- `experiments/ideas/`, `experiments/exploration/`, `experiments/plans/`, and `experiments/results/` remain the authoritative artifacts. +- Linear mirrors repo state. It never overrides repo intent. + +--- + +## Sync Map + +Persist Linear identities in: + +- `experiments/linear-sync/issue-.json` + +Use the sync map as the canonical external identity store for: + +- team id and team name +- project id, name, and URL +- root issue id, identifier, and title +- created label ids +- created document ids +- manifest task id to Linear issue mapping +- last sync mode and timestamp + +The sync map must be read before `project-state.md` for idempotent re-syncs. + +Lookup order: + +1. `experiments/linear-sync/issue-.json` +2. `project-state.md` +3. Live Linear lookup by exact team plus exact title + +--- + +## Naming Rules + +Project title: + +- `issue- — ` + +Root issue title: + +- `issue- — ` + +Child issue title: + +- `[issue-][] ` + +Document titles: + +- `issue- Plan Snapshot` +- `issue- Closeout Snapshot` + +--- + +## Default Workspace Rules + +If `/linear-bind` is run without a team argument: + +- If exactly one team exists, use that team +- If more than one team exists, fail explicitly + +Current expected workspace shape: + +- default team: `Vijaypmworkspace` +- issue statuses: `Backlog`, `Todo`, `In Progress`, `In Review`, `Done` +- no active cycles required for v1 + +--- + +## Label Taxonomy + +Ensure the parent label group exists: + +- `AI Product OS` + +Ensure these child labels exist under that group: + +- `Discovery` +- `Planning` +- `Execution` +- `Review` +- `Blocked` +- `Release Ready` +- `Completed` + +Also use the workspace-level `Feature` label on root and child issues unless a different work type is explicitly required by the repo artifact. + +--- + +## Status Mapping + +Repo stage to root issue workflow status: + +- `create-issue`, `explore` -> `Backlog` +- `create-plan` -> `Todo` +- `execute-plan`, `deslop` -> `In Progress` +- `review`, `peer-review`, `qa-test`, `deploy-check` -> `In Review` +- `learning` complete -> `Done` + +Repo stage to AI Product OS stage label: + +- `create-issue`, `explore` -> `Discovery` +- `create-plan` -> `Planning` +- `execute-plan`, `deslop` -> `Execution` +- `review`, `peer-review`, `qa-test` -> `Review` +- blocked state also applies `Blocked` +- successful `deploy-check` also applies `Release Ready` +- successful `learning` applies `Completed` + +Only one active stage label should be present at a time, except: + +- `Blocked` +- `Release Ready` +- `Completed` + +These may coexist when appropriate. + +--- + +## Document Snapshot Rules + +Plan snapshot document must include: + +- plan summary +- manifest summary +- repo file paths for the plan and manifest + +Closeout snapshot document must include: + +- postmortem summary +- learning summary +- repo file paths for postmortem and learning-related artifacts + +Use update-in-place when the sync map already stores a document id. + +--- + +## Child Issue Rules + +Create child issues only from `manifest-.json`. + +Each child issue description must include: + +- phase id and phase name +- assigned agent +- files to create +- files to modify +- verification command +- test file + +Child issues default to: + +- issue status `Todo` +- labels `Feature` and `AI Product OS/Execution` + +Do not auto-close child issues in v1. + +--- + +## Failure Policy + +Raise explicit errors for: + +- missing `active_issue` +- missing bind before sync, brief, or close +- missing manifest for `plan` sync +- missing cycle when `cycle` brief is requested +- multiple teams when no team argument is provided +- failed Linear API operations + +Linear write conflicts must recover by lookup rather than creating duplicates. + +Never use silent fallback. diff --git a/project-state.md b/project-state.md index 94924a4..aeb100c 100644 --- a/project-state.md +++ b/project-state.md @@ -127,7 +127,18 @@ ## Links +- 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). - docs_home: experiments/ideas/issue-007.md - demo: - analytics_dashboard: