Module 6: Working with Claude Workflows

Estimated time: 20 minutes

Overview

L3 distributes four GitHub Actions workflows to every registered repo. Together, they form an AI-powered development pipeline that can standardize issues, create implementation plans, and even write code — all triggered by labels and comments.

Workflow 1: standardize-issue.yml

Trigger: Every new GitHub issue (issues: [opened]) No label required — runs automatically.

What It Does

1. Checks if the issue already has <!-- l3-standardized --> in the body. If yes, skips (idempotency guard).
2. POSTs the raw issue to the ingestion service's /api/standardize endpoint
3. Claude returns a structured response: normalized title, formatted body, labels, and complexity
4. Updates the GitHub issue with the new title, body (with <!-- l3-standardized -->), and labels

This means every new issue — whether filed manually, by Marker.io, or from the Meeting Review — gets automatically standardized by Claude.

Workflow 2: assign-linear-project.yml

Trigger: Every new GitHub issue (issues: [opened]) Runs in parallel with standardize-issue.yml.

What It Does

1. Reads .github/linear-project.json to get the repo's Linear team
2. Waits 15 seconds for the Linear GitHub integration to sync the issue
3. Searches Linear for the matching issue and verifies it landed in the correct team
4. Logs the result (but doesn't force-move — the Linear integration is authoritative)

This is a verification workflow, not an assignment workflow. It catches misrouted issues.

Workflow 3: claude-code-plan.yml

Trigger: Label ai-plan is applied to an issue Timeout: 30 minutes, max 50 Claude turns

What It Does

1. Removes needs-review if present (since ai-plan supersedes it)
2. Moves the Linear issue to "In Progress"
3. Fetches the system prompt from Langfuse (falls back to embedded defaults)
4. Runs Claude Code Action with the superpowers plugin
5. Claude reads CLAUDE.md, explores the codebase, and creates an implementation plan
6. Saves the plan to docs/superpowers/plans/
7. Opens a draft PR containing only the plan file — no code changes

Output: A draft PR with a plan document. The PR title uses the format [Plan] [LINEAR-ID] Short description.

When to Use

Apply ai-plan when you want Claude to think through the approach before writing code. This is especially useful for:

• complexity:high issues that need architectural decisions
• Issues where you want to review the approach before implementation
• When you want a written plan to share with the team

Workflow 4: claude-code.yml

Trigger: Three distinct paths:

Timeout: 90 minutes, max 100 Claude turns

The needs-review Guard

• If needs-review is present AND the trigger was ai-triaged: the label is removed and execution continues
• If needs-review is present AND the trigger was a @claude comment: execution is skipped entirely

This prevents Claude from responding to comments on issues that haven't been reviewed yet.

Draft PR Continuation

When ai-triaged is applied, the workflow checks for existing draft PRs that reference the current issue. If one exists (created by claude-code-plan.yml), Claude checks out that branch and continues from the plan rather than starting fresh.

Complexity-Driven Behavior

Claude's approach varies based on the issue's complexity label:

Output

• If starting fresh: Claude creates a new branch and opens a PR with Fixes #N (auto-closes the issue)
• If continuing from a draft: the existing draft PR is promoted to ready-for-review, [Plan] prefix is stripped from the title, and Related to is replaced with Fixes
• If running low on turns: Claude opens a draft PR with whatever progress exists

The Label Flow

Here's how labels orchestrate the full pipeline:

Issue Created
    ↓
standardize-issue.yml adds: needs-review + type + platform + complexity
    ↓
Human reviews and chooses one:
    ├── "ai-plan" → Claude writes a plan (draft PR)
    │       ↓
    │   Human reviews plan, then applies "ai-triaged"
    │       ↓
    │   Claude continues from the plan → implements → PR
    │
    ├── "ai-triaged" → Claude implements directly → PR
    │
    └── "human-only" → Engineer implements manually

Claude Code Configuration

Every registered repo receives .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(*)", "Read(*)", "Write(*)", "Edit(*)", "Glob(*)", "Grep(*)"]
  },
  "enabledPlugins": {
    "superpowers@superpowers-marketplace": true
  }
}

The superpowers plugin (from github.com/obra/superpowers-marketplace) provides skills like brainstorming, writing plans, and TDD verification that Claude uses during workflows.

CLAUDE.md Conventions

Claude reads both the root and the most-specific nested CLAUDE.md when working in a subdirectory:

• Root CLAUDE.md — Monorepo structure, Linear team, project-wide conventions
• .ops/CLAUDE.md — Rules for editing templates (always edit in .ops/, never installed copies)
• platform/ingestion/CLAUDE.md — Ingestion service architecture, API patterns, testing
• Nested CLAUDE.md files — Package-specific conventions and commands

When writing a CLAUDE.md, focus on information that Claude can't derive from the code itself: architecture decisions, naming conventions, testing strategies, and things to watch out for.

System Prompts

All system prompts for workflows are managed in Langfuse and fetched at runtime from the ingestion service's /api/prompt?name=<prompt-name> endpoint. The two named prompts are ai-triaged and ai-plan. If the fetch fails, fallback prompts embedded in the workflow YAML are used.

Check Your Understanding

Checkpoints

Module Assessment