Backlog Hygiene, Label Cleanup, and Cycle Rebaseline — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Bring the Linear backlog, repo planning docs, branch conventions, and repo-flow skill into a consistent, platform-agnostic, post-CWS-82 state.

Architecture: Phase 1 performs all Linear API mutations (no repo changes). Phase 2 creates a Graphite stack of 4 PRs — each PR is one logical concern. The stack merges with gt merge (full stack), never individual PR merges.

Tech Stack: Linear MCP tools, Graphite CLI (gt), GitHub CLI (gh), make qa-local, bash scripts.

Spec: docs/superpowers/specs/2026-03-22-backlog-hygiene-design.md

File Map

Phase 1 — Linear Only (no repo files touched)

All mutations happen through Linear MCP tools. No files created or modified.

Phase 2 — Repo Changes (Graphite Stack)

PR 1 — Branch prefix rename codex/ → cws/:

PR 2 — Label taxonomy + agent-context rewrite:

PR 3 — repo-flow skill hardening:

PR 4 — Planning doc rewrite + task file:

Task 0: Create Linear Issue

Files: None (Linear API only)

Use mcp__claude_ai_Linear__save_issue with:

title: "[DEV] Backlog hygiene, label cleanup, and cycle rebaseline"
teamId: (CodeWithShabib team)
parentId: CWS-81's ID
priority: 2 (High)
labelNames: ["Workflow", "agent-task"]
projectId: [ORCHESTRATION] Agentic Workflow Design
milestoneId: M1 Contract Canonicalization

Record the created issue ID (e.g., CWS-93) — used for branch names, task file, and PR traceability throughout the rest of this plan.

Use mcp__claude_ai_Linear__save_issue to update state to In Progress.

Use mcp__claude_ai_Linear__list_cycles to find the active cycle, then update the issue’s cycle linkage.

Task 1: Phase 1 — Close/Cancel Issues

Files: None (Linear API only)

CWS-1, 2, 3, 4 were already cancelled in a prior session (Linear onboarding noise). Verify they show as Cancelled in Linear — no action needed unless they were reopened.

Use mcp__claude_ai_Linear__save_issue to:

This is done in Task 5 (PR 2). CWS-44 will be closed after agent-context.md is rewritten with all 8 required sections. Add a comment now:

Use mcp__claude_ai_Linear__save_comment:

Task 2: Phase 1 — Update Issues

Files: None (Linear API only)

Use mcp__claude_ai_Linear__save_issue:

For each issue, use mcp__claude_ai_Linear__save_issue:

For CWS-83 specifically, add to description: “Must include git history rewrite to remove infra work from public commit history.”

Use mcp__claude_ai_Linear__save_issue:

Use mcp__claude_ai_Linear__save_comment:

Use mcp__claude_ai_Linear__save_issue for each:

Use mcp__claude_ai_Linear__save_issue for each:

For each issue:

Use mcp__claude_ai_Linear__save_issue for each:

Read CWS-21 current state. Based on CWS-82 PR decomposition lesson, consider bumping priority. Update if warranted.

Use mcp__claude_ai_Linear__save_comment:

Task 3: Phase 1 — Project Updates and Label Cleanup

Files: None (Linear API only)

Use mcp__claude_ai_Linear__save_project for each:

(Blog Content Pipeline has no date — skip.)

Use mcp__claude_ai_Linear__list_issue_labels to get the full list with IDs.

For each of the 24 labels to delete, check which issues use them. Plan relabeling:

For each issue on an absorbed label, use mcp__claude_ai_Linear__save_issue to:

Note: The Linear MCP toolset has create_issue_label but no update_issue_label. If label description update is not available via MCP, use the Linear web UI to set the agent-task description to “Work to be executed by an AI agent”.

After all issues are relabeled, delete each label. Note: The Linear MCP toolset may not have a delete_issue_label tool. If not, use the Linear web UI to delete labels.

Labels to delete: Dev, Refinement-Needed, Merge-Ready, Review, Implementation, Editorial-Update, Editorial-New, Hybrid, Improvement, Feature, Bug, Agent, Human, Waiting-Agent, Waiting-Human, Linear, Codex, epic:dor-dod, epic:adr, epic:publish-draft, epic:git-hooks, epic:security, epic:triggers

Task 4: Phase 2 Setup — Create Branch and Stack Base

Files: None (git/Graphite setup only)

Important: The Linear issue ID from Task 0 is needed here. In all branch names below, replace <id> with the actual issue number (e.g., 93).

Run:

git status

Expected: clean working tree on main. If dirty, stash or resolve before continuing.

Run:

git pull origin main

Run:

git checkout -b cws/<id>-branch-prefix-rename main
gt track --parent main

Note: This branch itself uses the NEW cws/ prefix convention being introduced.

Task 5: PR 1 — Branch Prefix Rename (codex/ → cws/)

Files:

Not testable with unit tests — these are convention/config/doc changes. Validation is make qa-local + grep verification.

Change:

- Task branches use `codex/cws-<id>-<slug>`. (The `codex/` prefix is a repo convention, not a
  platform restriction.)

To:

- Task branches use `cws/<id>-<slug>`.

Change:

- Same branch convention: `codex/cws-<id>-<slug>` (the `codex/` prefix is a repo convention,
  not a platform restriction).

To:

- Same branch convention: `cws/<id>-<slug>`.

Change:

- Branch: `codex/cws-<id>-<slug>` (task) or `codex/phase-<n>-<slug>` (rollout)

To:

- Branch: `cws/<id>-<slug>` (task) or `cws/phase-<n>-<slug>` (rollout)

Change:

- Start repo-changing work from `main` on a fresh `codex/*` branch.

To:

- Start repo-changing work from `main` on a fresh `cws/*` branch.

Change:

- create a `codex/<type>-<slug>` branch

To:

- create a `cws/<type>-<slug>` branch

Change:

task_branch_pattern: '^codex/cws-\d+-[a-z0-9-]+$'
phase_branch_pattern: '^codex/phase-(\d+)-[a-z0-9-]+$'

To:

task_branch_pattern: '^cws/\d+-[a-z0-9-]+$'
phase_branch_pattern: '^cws/phase-(\d+)-[a-z0-9-]+$'

Change:

if [[ "$branch" =~ ^codex/cws-([0-9]+)-[a-z0-9-]+$ ]]; then

To:

if [[ "$branch" =~ ^cws/([0-9]+)-[a-z0-9-]+$ ]]; then

Change:

suffix="${inferred#codex/"${type}"-}"
branch_name="codex/phase-${phase}-${suffix}"

To:

suffix="${inferred#cws/"${type}"-}"
branch_name="cws/phase-${phase}-${suffix}"

Change:

if [[ "$branch" =~ ^codex/phase-([0-9]+)(-|$) ]]; then

To:

if [[ "$branch" =~ ^cws/phase-([0-9]+)(-|$) ]]; then

Change:

subject="${branch#codex/}"

To:

subject="${branch#cws/}"

Change:

- Start repo-changing work from `main` on a fresh `codex/*` branch using `make start-work`.

To:

- Start repo-changing work from `main` on a fresh `cws/*` branch using `make start-work`.

Change:

- [ ] `task_branch_pattern` allows task branches (`^codex/cws-\d+-...`)
- [ ] `phase_branch_pattern` remains phase-based (`^codex/phase-(\d+)-...`)

To:

- [ ] `task_branch_pattern` allows task branches (`^cws/\d+-...`)
- [ ] `phase_branch_pattern` remains phase-based (`^cws/phase-(\d+)-...`)

Read file first to confirm exact content, then update any codex/ branch references to cws/.

Change:

- Normal task branches use Linear-first naming (`codex/cws-<id>-...`).
- Rollout governance remains phase-based and sequential for rollout branches (`codex/phase-<n>-...`).

To:

- Normal task branches use Linear-first naming (`cws/<id>-...`).
- Rollout governance remains phase-based and sequential for rollout branches (`cws/phase-<n>-...`).

Run (searches for codex/ as a branch prefix pattern, not as a directory path):

rg "codex/(cws|phase|[a-z]+-)" AGENTS.md CLAUDE.md .agents/skills/repo-flow/SKILL.md .agents/skills/repo-flow/references/branch-pr-merge.md .github/pull_request_template.md scripts/create-pr.sh scripts/start-phase.sh scripts/run-codex-checks.sh .agents/skills/repo-flow/scripts/infer-pr-metadata.sh .codex/prompts/repo-workflow.md .codex/docs/multi-agent-rollout-checklist.md .codex/docs/multi-agent-red-team.md .codex/docs/workflows.md .codex/rollout/active-plan.yaml

Expected: zero matches. If any remain, fix before proceeding.

Also verify with a broader search (will match .codex/ directory paths — those are expected and fine):

rg "codex/" AGENTS.md CLAUDE.md .agents/skills/repo-flow/SKILL.md .github/pull_request_template.md

Expected: zero matches in these non-.codex/ files. The .codex/ directory name is intentionally unchanged — that is the Codex platform config directory, not a branch prefix.

Run:

make qa-local

Expected: all checks pass. If any fail, fix and re-run. If it fails twice consecutively, stop and report.

Run:

gt create --all -m "refactor: rename branch prefix codex/ to cws/"

Task 6: PR 2 — Label Taxonomy in AGENTS.md + agent-context.md Rewrite

Files:

Add after the ## Platform Applicability section (after line 169), before ## Bash Security Baseline:

## Label Taxonomy

Approved labels (15). Do not create new labels without human approval.

| Label | Purpose |
|-------|---------|
| `Spec` | Has written specification |
| `Ready` | Pickup-ready, no blockers |
| `agent-task` | Work to be executed by an AI agent |
| `human-task` | Human executes |
| `Infra` | Infrastructure/tooling domain |
| `Workflow` | Process/workflow domain |
| `epic:dx-setup` | DX setup epic |
| `epic:editorial-qa` | Editorial quality epic |
| `epic:ci-pipeline` | CI pipeline epic |
| `epic:safety` | Safety and security epic |
| `epic:skills` | Skill authoring epic |
| `epic:reasoning` | Reasoning skills epic |
| `epic:slack` | Slack integration epic |
| `epic:dispatch` | Dispatch workflow epic |
| `epic:agents-config` | Agent config epic |

Replace entire file with the CWS-44 8-section schema. Content should reflect current state after Phase 1 Linear mutations complete. The 8 required sections:

# Agent Context Ledger (Linear-Synced Cache)

This file is a bounded cache for agent continuity.

- Source of truth: Linear issues, projects, initiatives, and documents.
- Freshness SLA: 24 hours.
- Planning memory file: `docs/planning/linear-reorg-2026-03.md`
- Either platform (Codex or Claude Code) can update this ledger.
- If stale, do not trust this file until a new Linear sync pass is completed.

## Last Synced From Linear

- Synced at: `<current timestamp>`
- Synced by: `Claude Code`
- Scope: `CWS-93 backlog hygiene, label cleanup, and cycle rebaseline`
- Linear anchors:
  - `Content & Thought Leadership`
  - `Agentic Delivery Platform`
  - `Blog Content Pipeline`
  - `CWS-93` (In Progress)

## Stale After

- `<current timestamp + 24h>`
- Rule: if current time is later than this timestamp, run a new Linear sync before execution.

## Active Phase

- CWS-93 (backlog hygiene) is in progress.
- Phase 1 (Linear mutations) complete. Phase 2 (repo changes) in Graphite stack.
- CWS-80 (Done), CWS-82 (Done).

## Top Priorities

1. Complete CWS-93 backlog hygiene (this task)
2. CWS-81 normalization (parent)
3. Infrastructure chain: CWS-18 → CWS-5 → CWS-12

## Open Decisions

- CWS-14/48 voice profile interview: scheduling TBD
- CWS-83 repo split: deferred post-April 19, requires git history rewrite
- Cycle date correction: not available through current Linear MCP toolset

## Active Risks

- Editorial chain blocked until voice profile interview (CWS-14/48)
- Semgrep post-tool hook erroring (no SEMGREP_APP_TOKEN) — non-blocking but noisy

## Next 10 Actions

1. Merge CWS-93 Graphite stack
2. Close CWS-44 after agent-context.md rewrite merges
3. Close CWS-7 after label cleanup merges
4. Update CWS-81 remaining scope
5. Pick up CWS-18 (next infrastructure task)
6. Pick up CWS-5 (blocked by CWS-18)
7. Schedule CWS-14 voice profile interview session
8. Pick up CWS-13 (Vale config — unblocks CWS-25, CWS-32)
9. Pick up CWS-23 (unblocks CWS-36, CWS-31, CWS-38)
10. Correct Linear cycle dates through supported tooling

## Recent Completions

- CWS-80: Workspace rebaseline and drift audit (Done, merged)
- CWS-82: Dual-platform pivot — Claude Code as peer platform (Done, merged)
- CWS-1, 2, 3, 4: Cancelled (Linear onboarding noise)

Exact timestamps and issue ID will be filled at execution time based on current state.

Run:

rg -n "Last Synced|Stale After|Active Phase|Top Priorities|Open Decisions|Active Risks|Next 10 Actions|Recent Completions" docs/agent-context.md

Expected: 8 matches, one per section header.

Run:

make qa-local

Expected: all checks pass.

Run:

gt create --all -m "chore: add label taxonomy and rewrite agent-context per CWS-44"

Task 7: PR 3 — repo-flow Skill Hardening

Files:

Add after the ## Done Criteria section (after line 57), before ## Rules:

## Gotchas

- `gt sync --force` after partial stack merges deletes branches and closes PRs. Never use it to
  reconcile a partially merged stack.
- `gh pr merge` directly bypasses validation gates in `make finalize-merge`. Always use
  `make finalize-merge PR=...` for single-PR merges.
- For Graphite stacks, `make finalize-merge` only merges one PR and does not manage Graphite
  metadata or retarget children. Use `gt merge` or Graphite web for full-stack merges.

Append to the existing ## Rules section:

- MUST NOT use `gh pr merge` directly — use `make finalize-merge PR=...`.
- MUST NOT use `gt sync --force` to reconcile after partial stack merges.
- For stacks, MUST use `gt merge` or Graphite web, not individual PR merges.
- MUST NOT create bulk commits — use atomic commits (one logical change per commit).

Add after the Rules section:

## Validation Loop

1. Run `make qa-local`. If it fails, fix issues and re-run.
2. Do not commit until `make qa-local` passes.
3. If `make qa-local` fails twice consecutively, stop and report (per AGENTS.md loop safety).
4. If `make qa-local` fails, invoke `superpowers:systematic-debugging` to diagnose.

Add after the Validation Loop section:

## Cross-Skill References

These are Claude Code plugin skills — MUST be invoked during repo-flow execution:

- `superpowers:verification-before-completion` — invoke before claiming work is done.
- `superpowers:systematic-debugging` — invoke if `make qa-local` fails.
- `commit-commands:commit` — invoke for commit creation conventions.

The branch prefix on line 60 should already read cws/* from PR 1. Verify:

grep "codex/" .agents/skills/repo-flow/SKILL.md

Expected: zero matches.

The branch prefix on line 6 should already read cws/ from PR 1. Verify:

grep "codex/" .agents/skills/repo-flow/references/branch-pr-merge.md

Expected: zero matches (Stack Merge Policy section uses gt merge / make finalize-merge, not branch name patterns).

Run:

make qa-local

Expected: all checks pass.

Run:

gt create --all -m "chore: harden repo-flow skill per CWS-82 lessons and agentskills.io"

Task 8: PR 4 — Planning Doc Rewrite + Task File

Files:

Create docs/tasks/CWS-93.md:

# CWS-93: Backlog Hygiene, Label Cleanup, and Cycle Rebaseline

- Linear: https://linear.app/codewithshabib/issue/CWS-93
- Parent: CWS-81
- Branch: `cws/<id>-backlog-hygiene`
- Spec: `docs/superpowers/specs/2026-03-22-backlog-hygiene-design.md`
- Plan: `docs/superpowers/plans/2026-03-22-backlog-hygiene.md`

## Scope

Phase 1: Linear mutations (label cleanup 37→15, issue updates, project date removal, cycle rewrite)
Phase 2: Graphite stack of 4 PRs (branch prefix rename, AGENTS.md+agent-context, repo-flow hardening, planning doc rewrite)

## Evidence

- `make qa-local` passed on committed tree
- CWS-44 8-section validation passed
- Branch prefix grep returned zero matches
- Label count reduced from 37 to 15

Rewrite the file with:

Key content to absorb from old agent-context.md:

Updated cycle layout should reflect:

Run:

make qa-local

Expected: all checks pass.

Run:

gt create --all -m "docs: rewrite cycle layout and planning doc post-hygiene cleanup"

Task 9: Submit and Verify Stack

Run:

gt submit --stack --no-interactive --publish

This creates 4 PRs in Graphite, properly stacked.

Run:

gt log --stack

Expected: 4 PRs listed, all targeting correct bases.

Check GitHub checks:

gh pr checks <pr-number>

for each PR. Wait for CI to complete. If any fail, fix on the appropriate branch, amend, and gt submit --stack --no-interactive.

Review each PR’s diff to confirm:

Before claiming stack is ready, invoke this skill to verify all acceptance criteria.

Task 10: Post-Merge Cleanup

After the stack is merged (via gt merge or Graphite web):

Use mcp__claude_ai_Linear__save_issue:

Should already be closed from Task 1 Step 1.

Use mcp__claude_ai_Linear__save_comment:

Use mcp__claude_ai_Linear__save_issue:

Invoke remember:remember skill to save handoff state.