# Claude Code Setup Instructions

**Paste these instructions to Claude Code and it will configure the agentic coding workflow in your project.**

Copy everything below the line, open Claude Code in your project directory, and paste it as a prompt.

---

## Prompt to paste into Claude Code

```
Set up the agentic coding workflow in this project. Follow these steps exactly:

### Step 1 — Create CLAUDE.md

Create a CLAUDE.md file in the repo root. Analyze the existing codebase to fill in the details:

- Describe the project (what it does, what stack it uses)
- Document the file structure
- Document the git workflow (branch strategy, commit conventions)
- List how to run tests
- List any known gotchas or conventions
- Add a "Co-Authored-By: Claude Code <noreply@anthropic.com>" trailer convention

### Step 2 — Create the agentic workflow skill

Create `.claude/skills/agentic-workflow.md` with this content:

---
# Agentic workflow skill

## Reading the backlog
When asked to plan or work on issues:
1. Read open issues labeled `sprint-ready`
2. Group related issues by `area:*` label
3. Propose a sprint plan before executing

## Issue metadata
Issues in this project use a metadata footer:
```
<!-- agentic-workflow-v1 -->
source: observation | spec | roadmap | customer
area: [component or URL path]
captured_at: [ISO 8601]
```
Parse these fields when planning sprints.

## Sprint composition rules
- Never mix unrelated areas in one PR
- Keep PRs under 500 lines of diff when possible
- If an issue is labeled `needs-spec-expansion`, ask for clarification before executing
- If an issue is labeled `blocker`, prioritize it above all others
- If an issue is labeled `hold`, skip it entirely

## PR conventions
- Title: concise, imperative ("Add settings validation", not "Added")
- Body: reference issues with "Closes #N"
- Always run the test suite before marking ready for review
- Include a summary of what changed and why in the PR body
---

### Step 3 — Create GitHub labels

Using the GitHub CLI, create these labels in the repo:

```bash
gh label create "source:observation" --color "0E8A16" --description "Captured during testing"
gh label create "source:spec" --color "1D76DB" --description "Feature specification"
gh label create "source:roadmap" --color "5319E7" --description "Planned roadmap item"
gh label create "source:customer" --color "FBCA04" --description "External feedback"
gh label create "sprint-ready" --color "0E8A16" --description "Ready for agent sprint"
gh label create "needs-triage" --color "D93F0B" --description "Needs human attention"
gh label create "needs-spec-expansion" --color "F9D0C4" --description "Needs more detail"
gh label create "blocker" --color "B60205" --description "Priority — immediate action"
gh label create "hold" --color "EEEEEE" --description "Do not work on yet"
gh label create "sprint-plan" --color "C2E0C6" --description "Agent sprint plan"
gh label create "auto-sprint" --color "BFD4F2" --description "PR from automated sprint"
gh label create "morning-brief" --color "D4C5F9" --description "Daily review summary"
```

### Step 4 — Create GitHub Actions

Create `.github/workflows/auto-label.yml`:

```yaml
name: Auto-label issues
on:
  issues:
    types: [opened]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.issue.body || '';
            const labels = [];
            
            const source = body.match(/source:\s*(\w+)/);
            if (source) labels.push(`source:${source[1]}`);
            
            const area = body.match(/area:\s*(.+)/);
            if (area) labels.push(`area:${area[1].trim()}`);
            
            if (!body.includes('needs-triage')) {
              labels.push('sprint-ready');
            }
            
            if (labels.length > 0) {
              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.payload.issue.number,
                labels,
              });
            }
```

Create `.github/workflows/close-sprint.yml`:

```yaml
name: Close sprint plans on merge
on:
  pull_request:
    types: [closed]

jobs:
  close:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const body = context.payload.pull_request.body || '';
            const refs = body.match(/Closes #(\d+)/g) || [];
            for (const ref of refs) {
              const num = ref.match(/\d+/)[0];
              await github.rest.issues.update({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: parseInt(num),
                state: 'closed',
              });
            }
```

### Step 5 — Verify the setup

After creating everything:
1. List the files you created and confirm they exist
2. Run `gh label list` to verify labels were created
3. Summarize what the workflow does in plain language
4. Suggest the first testing sweep the user should do

Commit all new files with message: "chore: set up agentic coding workflow (CLAUDE.md, skill, labels, actions)"
```

---

## What this sets up

After pasting the prompt above, Claude Code will create:

| File | Purpose |
|---|---|
| `CLAUDE.md` | Project context auto-loaded every session |
| `.claude/skills/agentic-workflow.md` | Sprint planning and execution rules |
| `.github/workflows/auto-label.yml` | Auto-labels issues from metadata footer |
| `.github/workflows/close-sprint.yml` | Closes referenced issues when PRs merge |
| 12 GitHub labels | The complete label schema for the workflow |

## What you do next

1. **Set up nightly routines** in Claude Code (see Chapter 4 of the playbook):
   - Planner routine at 9 PM
   - Executor routine at 10 PM
   - Morning briefer at 7 AM

2. **Run your first testing sweep** using voxspek or any voice capture tool:
   - Navigate your app
   - Speak observations: "The settings page has no empty state", "The nav doesn't highlight the active page"
   - Each becomes a structured GitHub issue with the metadata footer

3. **Review the morning brief** the next day and merge your first overnight PRs.

---

## Where human judgment is irreplaceable

AI agents excel at execution. They cannot do these things — only you can:

| Human responsibility | Why agents can't do it | How voxspek helps |
|---|---|---|
| **Vision & strategy** | Agents don't know your market, users, or business model | Spec mode: voice a feature idea → structured acceptance criteria |
| **Spec & roadmap** | Agents execute specs, they don't write them from user insight | Spec mode: capture requirements while browsing references |
| **Testing & curation** | Agents don't know if a feature "feels right" in context | Capture mode: 15 observations in 20 minutes, zero typing |
| **UI/UX commentary** | Agents don't perceive visual consistency or flow integrity | Capture mode: speak what looks wrong, AI structures it |
| **PR review & acceptance** | Agents don't know which PR will embarrass you in a demo | Review mode: classify PR feedback as blocker/comment/approve |

The overnight loop automates everything else. Your job is the five things above — and doing them fast enough that the loop stays tight.

---

*Download the full playbook at [voxspek.com/playbook](https://voxspek.com/playbook)*