It worked pretty well for that. But I ran into a problem I didn't really anticipate.

The Gap I Didn't Think About

SAPA gets you to what I called Phase Briefs. They look something like this:

# Phase Brief: Core Module

## Context
Greenfield - first phase after project setup

## Objective
Implement the primary data processing pipeline

## Deliverables
- [ ] pipeline.rs module
- [ ] CLI commands for processing
- [ ] Configuration loader

## Acceptance Criteria
- Processes input files correctly
- Handles errors gracefully
- Works on Windows and macOS

And that's... fine? Like, a human reading that knows what to do. But I wasn't handing it to a human. I was handing it to Claude Code.

What I kept running into was Claude Code asking me clarifying questions. "What's the file structure look like?" "Which error handling crate should I use?" "Where does the config file go?"

All reasonable questions. But I was spending the first 20 minutes of every session just re-explaining context that probably should have been written down somewhere.

The brief told Claude Code what to build. It didn't tell it how.

What I Started Doing Instead

So I started writing longer specs. Instead of bullet points, I'd include actual file paths, code scaffolds, validation steps, that kind of thing. More like a technical design doc than a brief.

The sessions got way more productive. Claude Code would just... go. For hours sometimes, without stopping to ask me things it should already know.

Eventually I realized I was doing the same expansion every time. Brief comes in, I flesh it out, Claude Code executes it. Same pattern over and over.

So I turned it into a skill.

What the Skill Does

I'm calling it SAPA Executor. It sits on top of the original SAPA framework and basically automates that expansion step.

The workflow ends up being:

1. Plan in Claude Web using SAPA, which gives you a PHASE_PLAN.md

2. Copy that file to your project

3. Tell Claude Code to generate the phases

4. Execute them one at a time

The skill handles three things that SAPA didn't:

Expansion is the main one. It takes those short briefs and turns them into detailed specs with file paths, scaffolds, implementation notes, test scenarios.

Tracking was something I added after losing my place a few times. There's a PHASE_INDEX.md that keeps track of which phases are done, which session UUIDs go with which phase, and any notes or discoveries along the way.

Validation is just making sure each phase actually works before moving on. Checklists, basically.

What the Format Looks Like

Here's a simplified version of what comes out of SAPA:

# Phase Plan: [Project Name]

## Overview
**Project**: [Name]
**Type**: [CLI / Desktop App / Library / etc.]
**Stack**: [Key technologies]

## Architecture Overview
[Diagram or description]

## Phases

### Phase 1: Project Setup
**Objective**: Initialize project with proper structure
**Deliverables**: Config files, module stubs, build scripts
**Acceptance**: Project compiles and runs placeholder

### Phase 2: Core Module
**Objective**: Implement primary functionality
**Deliverables**: Main module, types, error handling
**Acceptance**: Core feature works end-to-end

And here's what the skill expands Phase 2 into:

# Phase 02: Core Module

> **Status**: ⬜ Not Started
> **Estimated effort**: 2-3 hours
> **Dependencies**: Phase 01 (must be complete)

## Context

### What Exists
- Project scaffold from Phase 01
- Configuration loader
- Basic CLI structure

### What We're Building
The primary data processing pipeline.

## Deliverables

### 1. Pipeline Module

**File**: `src/pipeline.rs`

**Purpose**: Handles the core processing logic

**Implementation**:
- Create `Pipeline` struct with configuration
- Implement `process()` method
- Add error types in `src/errors.rs`

**Scaffold**:
```rust
pub struct Pipeline {
    config: Config,
}

impl Pipeline {
    pub fn new(config: Config) -> Self { ... }
    pub fn process(&self, input: &Path) -> Result<Output> { ... }
}
```

**Validation**:
- [ ] Compiles without warnings
- [ ] Unit tests pass

### 2. CLI Commands

**File**: `src/cli.rs`

**Implementation**:
- Add `process` subcommand
- Wire to Pipeline module
- Handle errors with user-friendly messages

## Validation Checklist

Before marking this phase complete:

- [ ] All deliverables implemented
- [ ] Code compiles without warnings
- [ ] `cargo test` passes
- [ ] Manual test: process sample input successfully
- [ ] Works on target platform(s)

## Test Scenarios

### Scenario 1: Happy Path
1. Run `app process input.txt`
2. **Expected**: Output file created, no errors

### Scenario 2: Missing Input
1. Run `app process nonexistent.txt`
2. **Expected**: Clear error message, exit code 1

## Handoff to Next Phase

Phase 3 will add [next feature]. It assumes:
- Pipeline module is stable
- Error handling patterns are established
- CLI structure supports additional commands

It's kind of verbose, but that's the point. Claude Code doesn't have to guess anything. It knows what files to create, what they should roughly look like, how to test them, and what the next phase expects.

The Tracking Thing

One problem I kept running into: phases don't always fit in one session.

I'd get halfway through something, close my laptop, come back the next day, and have no idea where I left off. Did I finish the error handling? Did I test on Windows yet? What was that weird edge case I found?

So the skill maintains an index file:

# Phase Index: [Project Name]

## Progress

| Phase | Name | Status | Session UUID | Notes |
|-------|------|--------|--------------|-------|
| 01 | Project Setup | ✅ Complete | 7f3a8b2c-... | |
| 02 | Core Module | ✅ Complete | 9d2e1f4a-... | Added retry logic |
| 03 | Extensions | 🟡 In Progress | a1b2c3d4-... | Windows path handling needed |
| 04 | Polish | ⬜ Not Started | | |

When I start a new session, I just point Claude Code at the index and it picks up where we left off. The notes column is for stuff I discovered during execution that might matter later. Things that didn't fit the original plan but need to be remembered.

How It Feels to Use

The skill responds to natural language. The main things I end up saying:

• "generate phases from the phase plan"

• "start phase 2"

• "complete phase 2" (runs through the checklist)

• "phase status"

It's not really a CLI. More like a conversation where Claude Code knows what I mean by "start phase 2" because it has the context.

What I Took Away From This

The thing I keep learning with AI tooling is that the information you need is different from the information the AI needs.

A Phase Brief makes sense to me because I can fill in the gaps. I know what "error handling" means in the context of this project. Claude Code doesn't, not unless I tell it.

SAPA was about figuring out how much planning you need. This is about figuring out how much detail Claude Code needs to execute without hand-holding.

They're kind of the same lesson applied at different points. Right-sizing the documentation for who's actually going to use it.

Links

I added the skill to the original SAPA gist:

• sapa-framework.md - the planning methodology (unchanged)

• sapa-quick-invoke.md - quick invoke for Claude Web (unchanged)

• sapa-executor-skill.md - the execution skill for Claude Code

• PHASE_INDEX_TEMPLATE.md - the progress tracking template

To install it:

mkdir -p ~/.claude/skills/sapa-executor
# Copy sapa-executor-skill.md to ~/.claude/skills/sapa-executor/SKILL.md

Or you can just drop the skill file into your project's .claude/skills/ directory if you want it scoped to one project.

If you've been using SAPA and running into the same handoff friction I was, maybe give this a shot. That's what I built it for.

Some of these ideas are genuinely good. Most are not. But here's what I noticed: I was spending the same amount of time "planning" the bad ideas as the good ones. I'd write a PRD for something that didn't need a PRD. I'd skip planning entirely for something that desperately needed structure. The result was a graveyard of half-started projects and a few over-documented ideas that never saw a single line of code.

So I built a framework. I call it SAPA.

What SAPA Actually Is

SAPA stands for Spectrum, Assessment, Prescription, Architecture. It's a methodology I use with Claude to take an idea from "I should build this" to "here are the exact steps to build this in phases."

The key insight: not every idea needs the same amount of planning. A weekend hack doesn't need a PRD. A product you're pitching to leadership doesn't need a napkin sketch. The problem is knowing which one you're dealing with.

SAPA forces me to figure that out before I start documenting.

The Four Steps

Spectrum is about seeing all your options. Before you write anything, understand the full range of planning documents that exist:

• Napkin sketch (for solo weekend builds)

• One-pager (for gut-checking with trusted people)

• Lean Canvas (for validating the business model)

• Product Brief (for aligning a small team)

• PRD (for cross-functional coordination)

• Technical Spec (for detailed implementation)

Most people jump straight to "I need a PRD" because that's what they've seen in companies. But if you're building alone, a PRD is overhead. If you're pitching leadership, a napkin sketch won't cut it.

Assessment is the interrogation. Before recommending a document, I ask myself:

• Is this idea validated? Have real users expressed interest?

• Who is building this? Just me? A team?

• What's the biggest risk? Technical feasibility? Market demand?

• Is this exploration, validation, or committed execution?

The answers determine the prescription.

Prescription is the output. Based on the assessment, I produce only what's needed. Nothing more. If I'm solo and unvalidated, I get a one-pager and go straight to building. If I need buy-in from others, I get a proper Product Brief. The framework prevents over-engineering the planning phase.

Architecture is where it gets interesting. Once I have the right planning doc, SAPA produces Phase Briefs. These are self-contained instructions for each development phase, formatted specifically for Claude Code.

Each Phase Brief contains:

• What exists from prior phases

• What this phase accomplishes

• Specific deliverables

• Technical constraints

• Acceptance criteria

I can hand a Phase Brief to Claude Code and say "build this." No re-explaining context. No starting from scratch. Just execution.

Why Phases Matter

Here's what I learned the hard way: if you try to build everything at once, you build nothing.

Phases force incremental progress. Each phase delivers something working. Something testable. Something you can show someone and get feedback on before you've invested 40 hours.

The phases are sized for a single Claude Code session. Roughly 1-4 hours of work each. Small enough to finish. Large enough to matter.

A Real Example

I had an idea for a product called "Infinite Intern." The concept: AI agents that work like employees, not chatbots. You hire them, give them job descriptions, assign tasks, review their work, provide feedback. They learn over time.

Without SAPA, I would have either:

1. Started coding immediately with no plan (and gotten lost in scope creep)

2. Written a 20-page PRD that took longer than actually building the thing

With SAPA, I did an assessment. Solo builder. Unvalidated idea. Technical feasibility is low risk (I know the stack). Market demand is the real question.

Prescription: Product Brief + Phase Plan. Skip the PRD. Skip the Lean Canvas. Get just enough structure to start building, then validate with real users.

The output was 8 phases:

1. Foundation (infrastructure, basic agent structure)

2. Intern Execution (actually performing tasks)

3. Review and Feedback (human-in-the-loop)

4. Frontend: Bullpen Dashboard

5. Frontend: Hiring Flow

6. Frontend: Review Queue

7. Additional Intern Types

8. Polish and Scheduling

Each phase has a brief. Each brief is ready for Claude Code. I can work through them sequentially, shipping something functional after each one.

The Meta Point

SAPA is a framework for working with AI. But it's really a framework for working with yourself.

The AI doesn't care if you write a PRD or a napkin sketch. The AI will happily help you over-plan or under-plan. The value of SAPA is that it forces you to stop and think about what you actually need before you start producing artifacts.

I've been using it for a few months now. The graveyard of half-started projects is smaller. The ratio of ideas-to-shipped-code is higher. That's the only metric that matters.

Get the Framework

I've packaged SAPA into a document you can drop into any Claude conversation. It includes:

• The full methodology

• Templates for every artifact type

• Instructions for producing Phase Plans and Phase Briefs

• An example showing the complete output

You can use the quick invoke version (just paste it with your idea) or the full framework (for understanding the methodology).

The framework is designed for Claude, by someone who uses Claude. It's opinionated. It's practical. It works.

If you're drowning in ideas and starving for shipped projects, give it a shot. The worst case is you spend 10 minutes thinking about your idea before you start. The best case is you actually finish something.

That's the whole pitch. Go build something.

Have questions about SAPA or want to share how you're using it? Find me on LinkedIn or GitHub.

It's not that people aren't smart. It's that when you explain something they already know, like a database or a container or whatever, they can picture it in their head. They've got something to attach your words to.

But when you're explaining an emerging standard like SPIFFE? There's nothing there. You're basically asking their brain to build something out of thin air.

So I figured maybe I should just... build the picture for them.

The Passport Thing Doesn't Work

People in the SPIFFE community like to use a passport analogy. Your SPIFFE ID is like your passport number, your SVID is like the physical passport, it expires and gets renewed, etc.

It's fine. But it kind of assumes everyone travels internationally.

Here's what I actually know for sure: pretty much everyone has worked at a company with a badge system.

You get hired. Security takes your picture and gives you a badge. Badge expires eventually. You get a new one. You tap it to get into the building. You show it to prove you work there.

That's SPIFFE. Same thing. But for software instead of people.

So I Built This Thing

It's called The Secret Lives of Identity. It's an interactive visualization that walks through SPIFFE and SPIRE from scratch. No assumed knowledge.

The name comes from The Secret Lives of Data by Ben Johnson, which is this really well done visualization of the Raft consensus algorithm. That project kind of showed me what's possible when you stop trying to explain something with words and just show it.

The badge metaphor runs through the whole thing:

• Your SPIFFE ID is like your employee ID number. It's permanent, doesn't change.

• Your SVID is your actual badge. Expires, gets renewed automatically.

• The SPIRE Server is corporate HQ. Issues badges, keeps track of everyone.

• The SPIRE Agent is the security desk on your floor. Verifies you locally, hands out badges.

• Attestation is proving you actually work here before anyone gives you a badge.

• mTLS is two employees showing each other their badges before they'll share anything.

Once you frame it that way, people get it. The metaphor does most of the work.

It Was Too Long

First version had like 90 frames. Everything. Attestation details, selectors, rotation, federation, trust bundles, all of it.

I showed it to some people at AWS re:Invent who'd never touched SPIFFE before. They actually understood it, which was great. But I kept hearing the same thing:

"It's kind of long."

Yeah. Fair.

Not everyone has 30 minutes. Some people just need to know what SPIFFE is so they can decide if they care. They don't need the deep dive yet.

So I split it into three tracks:

Each one tells a complete story. Bronze isn't a teaser for Silver. It's its own thing. You walk away understanding SPIFFE even if you never click Silver.

Workloads Aren't People

One thing I went back and forth on: how do you actually show a workload?

First instinct was a person icon. Fits the badge metaphor, employees have badges, makes sense.

But then... SPIFFE is about non-human identity. That's the whole point. If the workload looks like a person, people are gonna think "oh so like logging in" and that's not it at all.

Ended up going with a circuit chip thing. Like a processor with traces coming out of it. Reads as "machine" without looking like a server rack. The center of the chip is where the identity lives. When it's attested, it glows gold. When it's not, it's gray with a question mark.

Small thing but it actually makes a difference in how the whole thing feels.

What I Took Away From This

Building this kind of reinforced something I already sort of knew: education is a design problem.

Being accurate isn't enough. You have to be clear. And clear doesn't mean dumbed down. It means finding the right abstraction. Right metaphor. Right order to show things.

SPIFFE is a solid standard. SPIRE works. But adoption depends on people actually understanding it, and that depends on someone taking the time to bridge the gap between what it technically is and what it feels like.

That's what I was trying to do anyway.

Links

The site: thesecretlivesofidentity.com

The code: github.com/infamousjoeg/thesecretlivesofidentity

It's open source, Apache 2.0. If something's wrong, open an issue. If you want to improve it, PRs welcome.

And if you know someone who keeps struggling to explain workload identity to their team or their leadership or whoever... maybe send this their way. That's who I built it for.