The Spec-First Stack: /goal, Skill Audits, and Why Your Workflow Just Changed

Three separate sources today, all converging on the same structural shift: the era of interactive, turn-by-turn Claude Code sessions is ending. What's replacing it is a spec-first, autonomous execution model where your job is to write well-structured inputs, then get out of the way. Jones covers the /goal command mechanics, Nystrom (via Rachitsky's podcast) shows how Notion runs this at production scale, and Kashef diagnoses why your skill library is silently degrading the quality of everything you're building.

Let's go layer by layer.

The Five Shifts Happening Right Now

Jones's framing from "Vibe Coding is Dead" is worth internalizing as a mental model before getting into tactics:

Shift 3 and 4 are where /goal lives. Instead of the REPL loop — send a message, review the diff, send a correction — you front-load everything into a structured goal, hand it a spec, and let it run until it declares completion. This only works if your spec documents are clean, which is the entire argument for spec-first development.

/goal: What It Actually Does and How to Structure It

Jones has run this against both Codex CLI and Claude Code. Here's the mechanism:

/goal tells the agent to continue executing autonomously until it determines the goal has been met, rather than pausing for approval at each tool-use step. This is not just "autoApprove=true" — it changes the agent's internal termination condition. Instead of "do what the user asked and stop," it becomes "execute until goal criteria are satisfied."

The practical implication: your goal statement is now a termination spec, not a task description. A vague goal produces unpredictable termination. A goal with measurable exit conditions produces reliable output.

Minimal Working Structure

/goal Build the authentication module as specified in @prd.md and @product-roadmap.md.
Goal is complete when:
- All routes in the auth section of the roadmap are implemented
- Unit tests pass for each route
- No TypeScript errors
- README updated with setup instructions

Jones's actual workflow for a full app build:

1. Create prd.md — product requirements document (what it does, who uses it, core flows)
2. Create product-roadmap.md — phased feature list with clear milestones
3. Reference both in the /goal command
4. Let Claude Code run

The agent uses the roadmap as a checklist and the PRD as the acceptance criteria. It knows it's done when the roadmap items are checked off AND the PRD requirements are satisfied.

Gotchas Jones Flagged

• Don't use /goal without spec files. A goal without grounding in documents is just a long chat session. The agent drifts.
• Ambiguous success conditions produce premature termination. If your goal says "build the app," the agent will build something and declare done. Include explicit completeness checks.
• File references must be accurate. @prd.md fails silently if the file isn't in scope. Verify paths before running.
• Compare output against your roadmap manually before accepting. Jones showed side-by-side Codex vs Claude Code builds — Claude Code produced more complete feature coverage but differed in architecture choices.

The Spec-First Workflow at Production Scale: Notion's "Boxy"

Rachitsky's episode with Ryan Nystrom is the production-scale proof of everything Jones is describing for solo builders.

Spec-driven development: The AI engineering workflow at Notion | Ryan Nystrom

Notion built an internal system called Boxy: engineers @mention Codex from within a Notion comment, and 20 minutes later they get a full pull request with screenshots. The agent runs in a VM, has full repo access, and handles the entire implementation cycle. No editor required.

But the piece that maps directly to Brian's /goal work is Nystrom's spec-first development protocol:

"The spec becomes a changelog — version control for how a feature actually works."
— Ryan Nystrom

This is a critical architectural insight. When the spec lives in the repo:

• Future agents can read it for context
• Code reviewers know what was intended vs. what was built
• When the feature changes, the spec changes — both are versioned together

Why This Matters for Your /goal Setup

Jones's workflow of using prd.md + product-roadmap.md is the right instinct. Nystrom's production pattern adds two refinements:

1. Commit the spec. Don't just reference it — put it in the repo. This gives the agent (and future agents) stable, version-controlled ground truth.
2. Spec = verification criteria. The agent at Notion verifies its own output against the spec before opening the PR. Your /goal command should explicitly instruct Claude Code to do the same: "After implementation, verify each spec item is satisfied before declaring complete."

The CI Speed Constraint

Nystrom runs Project Afterburner specifically to cut Notion's CI time to 25% of current. This sounds like infra ops but it's actually an agent workflow bottleneck: when an agent spawns a PR and waits for CI, the agent's context is burning while CI runs. Slow CI = expensive agent loops = degraded results from context pressure.

For your setup: if you're running /goal tasks that trigger tests, watch your test suite runtime. Slow tests will either cause the agent to wait (expensive) or skip verification (dangerous). Fast CI is a prerequisite for autonomous agent workflows, not a nice-to-have.

Why Your Skill Library Is Probably Hurting You

Kashef's video addresses a failure mode that becomes critical exactly when you start running longer autonomous tasks: skill bloat and silent overlap.

The core mechanism:

Kashef calls this the description truncation cliff — when you have too many skills loaded, Claude truncates skill descriptions in the context window. The skill appears to be active but its full instructions never get processed. You get partial, inconsistent behavior with no error message.

The silent overlap problem: if you have four skills that each handle some aspect of code formatting, Claude may apply rules from multiple skills simultaneously, producing output that satisfies none of them completely.

The Reverse Meta Prompting Protocol

Kashef's fix is called reverse meta prompting: instead of writing a skill and hoping it works, you run the skill against the agent and have a subagent analyze what the skill actually produced vs. what you intended. This surfaces gaps and conflicts programmatically.

The protocol:

1. Run your skill on a real task
2. Use a secondary agent (Kashef uses claude-code-guide agent) to compare output to your intent
3. Identify divergence points
4. Consolidate or prune

His demo showed 4 overlapping skills being consolidated into 1. The consolidated skill produced better output than any of the four individually, because the instructions were coherent rather than competing.

The Skill Audit for /goal Users

If you're planning to run /goal for full app builds, your skill library quality matters more than in interactive sessions. In a 60-turn /goal run, a conflicting formatting skill will produce inconsistent code across 60 instances. In an interactive session, you catch it after 3.

Kashef's 8-point pruning checklist (from the video at ~10:13):

1. Does this skill have a feedback loop? (Can you measure whether it worked?)
2. Does this skill overlap with another? (Test by disabling it — does output change?)
3. Is this skill task-specific or general? (Task-specific skills should be in-prompt, not persistent)
4. Does the description fit without truncation? (Keep it under the threshold where Claude stops reading)
5. Does this skill encode a decision that should be in the PRD instead?
6. Would a subagent test reveal divergence from intent?
7. Is this skill compensating for a bad prompt habit rather than enabling a good workflow?
8. When did you last verify this skill still works with the current Claude version?

The last point is non-trivial. Claude's behavior shifts between versions. A skill tuned for Claude 3.5 Sonnet may produce subtly different (worse) results on 3.7. Without a feedback loop, you don't catch this.

Anatomy of a Skill That Scales

Per Kashef's framework (from ~4:59 in the video), a skill that holds up under autonomous agent conditions has:

• Single responsibility — one job, not a combined style + behavior + format rule
• Observable output — you can verify whether the skill applied correctly from the output alone
• No implicit assumptions — every constraint is explicit; nothing is left for Claude to infer
• Version notes — when it was last validated against current Claude behavior

Integrating All Three: The Full Stack Protocol

Here's how these three sources fit into a coherent daily workflow:

The Termination Criteria Checklist

Before every /goal run, your goal statement should answer:

• [ ] What files/features will exist when done?
• [ ] What tests must pass?
• [ ] What must NOT exist (regressions, deprecated patterns)?
• [ ] What output format signals completion? (e.g., "update product-roadmap.md to mark completed items")

Making the agent update the roadmap file as it completes items gives you a progress artifact and a clean termination signal.

The Autonomous Oversight Gap

Jones, Kashef, and Nystrom all touch on the same tension without fully resolving it: more autonomy = less oversight = more failure risk per session.

Jones's Shift 4 (moving from approving every request to letting the agent work autonomously) is the productivity gain. But Nystrom's Boxy system has explicit guardrails: VM isolation, PR-not-merge (human still approves merge), and screenshots for visual review. Kashef's subagent testing framework is another oversight layer.

The pattern that emerges:

• Input guardrails: Spec documents, clean skills, explicit termination criteria
• Process guardrails: VM isolation or branch isolation (never run /goal on main)
• Output guardrails: Agent self-verification against spec, human review of PR before merge

Don't skip the output guardrails because the input was clean. These are defense-in-depth, not sequential.

Where Today's Sources Disagree

One mild tension: Jones's approach is optimized for solo builders moving fast — get a working app from a PRD in one session. Nystrom's workflow at Notion is optimized for team coordination and audit trails — the spec is a communication artifact as much as a technical one.

For Brian's context (entrepreneur, solo or small team): Jones's approach is the right starting point, but Nystrom's "commit the spec" practice is worth adopting even solo. When you're running multiple parallel agents across multiple projects (Jones's Shift 5), version-controlled specs prevent you from losing track of what each project was supposed to be. The spec file is your external memory.

The other divergence: Jones doesn't discuss skill hygiene at all. Kashef's entire argument is that the quality of your skill library determines the quality of your /goal output. These aren't in conflict — Jones is addressing the new workflow pattern, Kashef is addressing the prerequisite infrastructure. Both are necessary.

Practical Setup: What to Build This Week

Day 1: Spec Infrastructure

• Create a /specs directory in your active project
• Write prd.md and product-roadmap.md for your next feature
• Reference Nystrom's workflow: dictate the idea, let Claude format it into a proper spec structure, then edit for accuracy

Day 2: Skill Audit

• Pull up your current skill list
• For each skill, disable it and run a representative task — measure whether output changes
• Identify any two skills that could conflict on formatting, style, or behavior
• Consolidate overlapping skills using Kashef's reverse meta prompting approach

Day 3: First /goal Run

• Start small: single module, not full app
• Write explicit termination criteria (the 4-item checklist above)
• Run on a feature branch, not main
• After completion, check: did the agent self-verify? Did it update the roadmap? Does output match spec?

Day 4: Parallel Agent Test

• Spawn two /goal sessions on different features simultaneously
• Observe: context pressure, skill conflicts, spec ambiguities surface differently at scale
• This is Jones's Shift 5 in practice

Failure Modes Reference

| Failure | Cause | Fix | |---|---|---| | Agent declares done prematurely | Vague termination criteria | Add explicit completion checklist to /goal | | Inconsistent code style across files | Overlapping format skills | Skill audit + consolidation | | Agent drifts from spec mid-run | No spec file reference in goal | Always include @prd.md and @roadmap.md | | Test verification skipped | No explicit verify instruction | Add "verify each spec item before declaring complete" | | Context degradation in long runs | Slow CI, skill bloat | Cut test runtime; prune skills | | Can't tell what agent was supposed to do | Spec not committed to repo | Commit spec alongside code | | Skill stops working after Claude update | No feedback loop | Add version notes; run subagent verification quarterly |

Today's One Action

Run a skill audit before your next /goal session.

Specifically: open your skill list, pick the two skills most likely to touch code formatting or style, disable both, run a test task, then re-enable them one at a time. If the output changes when you add the second skill, you have overlap. Consolidate them into one skill using Kashef's reverse meta prompting approach: run the task with both skills active, then ask a secondary Claude instance to identify where the instructions conflicted in the output.

Do this before you run /goal on anything substantive. A 60-turn autonomous session magnifies skill conflicts by 60x. Clean the library first, then set the goal.