Goal Workflow Usage Guide

Goal Workflow is a collection of AI-driven development workflow skills built for Claude Code / Codex. It breaks down the complete software development lifecycle into standardized steps, each driven by a dedicated Skill.

It enables AI agents to act like experienced engineers — from understanding requirements, breaking down tasks, writing code, reviewing quality, to final submission and merge — autonomously completing the entire process. You just describe the feature idea, and the workflow handles the rest.

Install all skills in one command via the npx skills CLI:

# Install all skills from this repository
npx skills add smallnest/goal-workflow

# Or install a specific skill
npx skills add smallnest/goal-workflow --skill prd
npx skills add smallnest/goal-workflow --skill prd-to-spec
npx skills add smallnest/goal-workflow --skill to-issues
npx skills add smallnest/goal-workflow --skill review-it
npx skills add smallnest/goal-workflow --skill ship-it
npx skills add smallnest/goal-workflow --skill humanize-it
npx skills add smallnest/goal-workflow --skill listenhub-tts
npx skills add smallnest/goal-workflow --skill insight-diagram
npx skills add smallnest/goal-workflow --skill refactor
npx skills add smallnest/goal-workflow --skill modern-go
npx skills add smallnest/goal-workflow --skill note-it
npx skills add smallnest/goal-workflow --skill code-to-spec
npx skills add smallnest/goal-workflow --skill smell

# Global install (available for all projects)
npx skills add smallnest/goal-workflow -g

# Install to a specific agent
npx skills add smallnest/goal-workflow -a claude-code

Prerequisites

Six-step closed loop, from requirements to delivery:

/prd transforms a vague feature idea into a structured product requirements document and breaks it down into independently implementable Issue cards.

How to Invoke

# Type directly in Claude Code
/prd Add a priority feature to our task management system

# Or use trigger phrases
Write PRD for: User registration with email and phone support
Requirements analysis: Add rate limiting capability to the API

Workflow

• Agent asks 3-5 clarifying questions (with letter options, reply quickly with "1A, 2C, 3B")
• Generates structured PRD based on answers (User Stories, Functional Requirements, Non-Goals, Acceptance Criteria)
• Presents PRD for review; confirm or adjust
• Saves PRD to tasks/prd-[feature-name].md
• Breaks down PRD into Issue list; presents for confirmation
• Selects creation mode (GitHub / Local / Baidu iCafe) and creates Issues

Output Example

# Generated Issue list
📋 Generated 4 Issues from PRD:

#1: Add priority field to database (backend, high)
#2: Display priority indicator (frontend, high) — depends on #1
#3: Add priority selector (frontend, medium) — depends on #1
#4: Filter tasks by priority (frontend, medium) — depends on #1, #2

/prd-to-spec transforms a product requirements document (PRD) into an implementable technical design SPEC. PRD says "what to build"; SPEC says "how to build it".

How to Invoke

# Type directly in Claude Code
/prd-to-spec tasks/prd-priority-system.md

# Or use trigger phrases
PRD to design: Convert priority PRD to technical plan
Technical spec: Generate SPEC based on prd-user-auth.md

PRD → SPEC Mapping

SPEC Output Structure (11 Chapters)

Workflow

• Locate PRD file (auto-scan tasks/ or manually specified)
• (Optional) Analyze existing codebase: architecture, tech stack, patterns, conventions (skip if no codebase — propose architecture from scratch)
• Ask 3-5 technical clarification questions (with options)
• Generate complete SPEC document
• Present for review; confirm or iterate
• Save to tasks/spec-[feature-name].md

/to-issues breaks down a PRD and/or SPEC into independently implementable Issues and creates them on your chosen platform. It can be used standalone — no need to run /prd first.

How to Invoke

# Type directly in Claude Code
/to-issues

# Or use trigger phrases
Create issues for: Create Issues from prd-user-auth.md
Break down issues: Break down implementable cards from SPEC
Generate cards: Break PRD and SPEC together into Issues

Input Sources

Creation Platforms

Workflow

• Locate input files (auto-detect or manually specify PRD/SPEC)
• Break down into Issue list; present for user review (can add, remove, edit, merge)
• Select creation platform (GitHub / Local / Baidu iCafe)
• Create one by one and output summary report

/goal is Claude Code's built-in goal-driven development mode. Pick an Issue card and the agent understands the acceptance criteria and implements end-to-end.

Usage

# Claude Code: specify GitHub Issue number
/goal #42

# Claude Code: specify local Issue file
/goal tasks/issues/issue-001-add-priority-field.md

# Codex: use --goal flag
codex --goal "Implement issue #42: Add priority field to database"

Agent Behavior

• Read Issue description and acceptance criteria
• Analyze codebase structure, understand context
• Write implementation code
• Run tests and type checks
• Verify UI changes in browser
• Confirm each acceptance criterion is met

/review-it performs automated review before committing, discovering potential issues and iteratively fixing them until the review passes.

How to Invoke

# Review uncommitted changes (default mode)
/review-it

# Review entire branch vs main
/review-it --mode branch

# Review + tests in parallel
/review-it --parallel-tests "npm test"

Review Principles

Review Modes

/ship-it is the standard closing workflow after implementation is complete: commit code, create PR, merge, add implementation summary, close Issue.

How to Invoke

# Invoke in Claude Code
/ship-it

# Or use trigger phrases
Submit code
Create PR and merge

Complete Flow

# Step 1: Commit code (link Issue)
git add <related files>
git commit -m "Add priority field to database (#42)"

# Step 2: Push branch
git push -u origin feat/issue-42-priority-field

# Step 3: Create PR (body includes Closes #42)
gh pr create --title "Add priority field" \
  --body "Closes #42 ..."

# Step 4: Merge
gh pr merge --squash --delete-branch

# Step 5: Close Issue (if not auto-closed)
gh issue close 42 --reason completed

Error Handling

/humanize-it rewrites specified documents to remove AI-generated feel. It automatically selects the most appropriate humanization strategy based on document type, iterating until the result meets quality standards.

How to Invoke

# Type directly in Claude Code
/humanize-it docs/architecture.md

# Or use trigger phrases
De-AI: Rewrite this document in natural language
Reduce AIGC: humanize docs/blog-draft.md

Sub-Skill Capability Matrix

Automatic Strategy Selection

Iteration Mechanism

• Auto-detect document type, select first rewriting skill
• After rewriting, score on 5 dimensions (AI trace removal / naturalness / information completeness / style consistency / readability)
• Score ≥ 80 passes; output result
• If not meeting target, switch to next skill, continuing to optimize on top of previous rewrite
• Auto-switch if same skill shows no improvement for 3 consecutive rounds
• After all skills used once, start a new round from the beginning with new combinations
• Maximum 42 iterations; output current best result

/listenhub-tts converts text to speech using the ListenHub API. Supports three synthesis modes, covering everything from short text to long-form content.

How to Invoke

# Type directly in Claude Code
/listenhub-tts Convert this text to speech

# Or use trigger phrases
Speech synthesis: Read README.md aloud
Generate audio: Read this article in Xiaoman's voice

Three Synthesis Modes

Voice Selection

Prerequisites

/insight-diagram generates UML diagrams, architecture diagrams, and flowcharts for any project. After analyzing the codebase, it lets users choose which diagram types to generate, renders them as HTML+SVG, and saves to the docs/ directory.

How to Invoke

# Type directly in Claude Code
/insight-diagram

# Or use trigger phrases
Generate architecture diagram: Analyze project structure and generate architecture diagram
Draw flowchart: Draw call flow diagram for this module
Generate UML: Generate class diagram and sequence diagram

Supported Diagram Types

A total of 17 diagram types, divided into structural and behavioral categories:

Structural Diagrams (Static)

Behavioral Diagrams (Dynamic)

★ Indicates most commonly used diagram types. Default recommended combination: Architecture Diagram + Sequence Diagram + Flowchart.

Workflow

• Analyze project codebase, identify key components and dependencies
• Present list of available diagram types; user selects which to generate
• Use architecture-diagram skill to render as HTML+SVG
• Save output to docs/ directory

/refactor provides expert-level code refactoring based on Martin Fowler's complete catalog from Refactoring 2nd Edition. By identifying code smells and applying proven refactoring techniques, it improves code maintainability, readability, and structure without changing external behavior.

How to Invoke

# Type directly in Claude Code
/refactor

# Or use trigger phrases
Refactor: Refactor UserManager class, it's too large
Code smell: This function has Feature Envy, fix it
Extract method: Break this long method into smaller functions

Code Smell Catalog

Identifies 22 code smells, organized into five categories:

Refactoring Techniques Catalog

40+ refactoring techniques in 6 categories, each with mechanical steps and comparison examples:

Safety Protocol

• Preparation Phase: Write characterization tests → commit current state → create refactoring branch
• Each Step: One change at a time → compile passes → all tests pass → commit
• Verification Phase: All tests pass → manual smoke test → self-review diff → final commit
• Iron Rule: Don't change external behavior, don't mix with feature changes, every step backed by tests

Language-Specific Guides

/modern-go automatically upgrades Go code to modern idioms and APIs, similar to go fix. It scans go.mod to detect the Go version, then batch-applies version-appropriate transformation rules to Go source files, covering 35+ rules from Go 1.0 through 1.26+.

How to Invoke

# Type directly in Claude Code
/modern-go

# Or use trigger phrases
Modernize: Modernize this project's Go code
Upgrade Go code: Update to Go 1.22 idioms
Gofix: Scan pkg/ directory and apply transformations

Workflow

• Read go.mod to get Go version
• Find .go files within target scope (specified file/directory/entire project)
• Scan each file for "Before" patterns, apply all transformations for versions ≤ project version
• Each transformation includes a concise comparison table and code examples (before/after)
• After editing, run goimports -w to clean imports
• Output transformation report: file count, transformations applied, rules skipped

Transformation Rule Catalog (by Go Version)

Safety Rules

• omitzero is suggested only, not auto-applied (may change JSON serialization behavior)
• SplitSeq is applied only when the loop body doesn't need index or full slice
• strings.Builder is applied only when concatenation happens inside a loop
• Each transformation that needs a new import auto-adds it and runs goimports to clean up

/note-it generates a structured implementation note for the current Issue after code implementation and review, recording design decisions, deviations, tradeoffs, and open questions. Output is saved as HTML in the docs/ directory.

How to Invoke

# Type directly in Claude Code
/note-it

# Or use trigger phrases
Record notes: Generate implementation notes for Issue #42
Implementation notes: Record decisions and deviations from this implementation

Note Contents

Output

• Auto-detect Issue number (from branch name or /goal context)
• Generate HTML format note file
• Save to docs/issue#XXXX.html
• If notes already exist for this Issue, prompt to append or overwrite

Positioning

/note-it sits between /review-it and /ship-it in the workflow, serving as the final checkpoint before submission — ensuring implementation intent is fully documented for future maintainers to understand the decision logic behind the code.

/code-to-spec analyzes an existing project's code, configuration, tests, and structure, then reverse-generates a complete SPEC document. The output can be used for project reconstruction, onboarding new team members, or comparing actual implementation against intended design.

How to Invoke

# Type directly in Claude Code
/code-to-spec

# Or use trigger phrases
Generate design doc: Analyze current project and generate SPEC
Reverse spec: Reverse engineer this project's specification
Generate SPEC document: Generate technical SPEC for src/ directory

Analysis Depth

SPEC Document Structure (12 Chapters)

Workflow

• Confirm analysis scope (entire repo / specified directory / specific aspects) and depth level
• Scan project: identify entry points, directory structure, dependency graph, API routes, data models
• Extract business rules: derive from validation functions, guard clauses, test assertions
• Synthesize and generate 12-chapter SPEC document
• Present for review; iterate based on feedback
• Save to docs/SPEC.md or user-specified location

/smell analyzes a codebase for architectural anti-patterns, code smells, and algorithmic complexity hotspots. It produces a detailed markdown report with severity levels, evidence, and a refactoring roadmap.

How to Invoke

# Type directly in Claude Code
/smell

# Or use trigger phrases
Code smell analysis: find code smells in this project
Architecture audit: detect architecture anti-patterns
Complexity scan: analyze code complexity and find hotspots

Detection Categories (8 Categories, 50+ Smells)

Report Structure

• Executive Summary with overall health assessment
• Architectural Style Detected vs. Expected
• Findings by severity (Critical / Warning / Suggestion)
• Dependency Graph Analysis and Module Health Scorecard
• Smell distribution across all 8 categories
• Refactoring Roadmap (Immediate / Short-Term / Long-Term)

Goal Workflow skills can be used across multiple AI Coding Agents:

Issue Creation Platforms

Q: Do I have to use all steps in order?

No. Each Skill is independent and can be used standalone. For example, if you already have Issues, you can start directly from /goal; if code is already written, you can use /review-it directly. But going through the full workflow yields the best results.

Q: Where does /goal come from? Why isn't it in the skills directory?

/goal is a built-in feature of Claude Code and doesn't require separate installation. The Issue format generated by this workflow's /prd perfectly matches what /goal expects as input.

Q: Can I use this in non-GitHub projects?

Yes. /prd supports saving Issues as local Markdown files or creating them in Baidu iCafe. /review-it only needs a local git repository. /ship-it currently depends on GitHub (gh CLI).

Q: How is /review-it different from manual code review?

/review-it is automated self-review, catching obvious issues before submission. It doesn't replace team code review, but rather improves code quality before PR creation, reducing the low-level issues reviewers need to point out.

Q: How big should an Issue be?

Each Issue should represent work an agent can complete in a single session — typically 1-3 files of changes with clear acceptance criteria. /prd automatically breaks down at this granularity, but you can adjust before confirming.

Q: How do I use this with Codex?

When installing via npx skills add, choose -a codex. In Codex, use codex --goal "..." instead of /goal. /review-it works universally across agents.

Q: Is /prd-to-spec required? When can I skip it?

Not required. /prd-to-spec is an optional step. PRD says "what to do"; SPEC says "how to do it". The distinction: an AI agent executing /goal inherently possesses the "how" capability — it automatically analyzes the codebase, understands existing architecture and conventions, and makes reasonable technical decisions during implementation. In other words, the AI agent is a living SPEC engine — it doesn't need it drawn on paper first.

Most small to medium features work perfectly fine with just PRD → /goal. The following scenarios justify the extra step of /prd-to-spec:

• Multi-person/multi-agent parallel development — need shared technical conventions to avoid divergent implementations
• Changes spanning multiple services/modules — architecture decisions have broad impact and rework costs are high
• Need maintained documentation — a formal technical reference for the team to consult later
• Compliance/review requirements — organizational process mandates design documents
• PRD is too vague — SPEC can supplement with technical details to reduce agent interpretation variance

If your project is single-developer, feature boundaries are clear, and the agent already reliably understands the project structure, skipping /prd-to-spec is entirely reasonable — and often more efficient. Treat it as an optional tool in your toolkit — bring it out only when needed.

Q: Where does the 42 iteration limit in /humanize-it come from?

The number 42 isn't due to any special iteration requirement, but a geek culture tribute to the classic sci-fi novel The Hitchhiker's Guide to the Galaxy. In the book, a supercomputer computes for 7.5 million years and arrives at "the Answer to the Ultimate Question of Life, the Universe, and Everything" — which is 42. In programming circles, this number is popular for two reasons:

• Sci-fi tribute: A well-known Easter egg among programmers, representing the ultimate answer.
• ASCII coincidence: In ASCII encoding, 42 corresponds to the asterisk *. In computer science, * is commonly used as a wildcard meaning "anything" or "everything is possible." So "the ultimate answer is 42 (*)" perfectly aligns with the philosophical joke that it's "whatever answer you want."

In practice, most documents reach quality standards within 3-5 iterations. The core of iteration is intelligent strategy switching — when one rewriting approach plateaus, it automatically switches to another. The three strategies complement each other to cover different types of AI traces.

Q: Does /humanize-it support English documents?

Currently, the three sub-skills of /humanize-it are primarily optimized for Chinese text. humanizer-zh's pattern detection rules partially work for English as well, but rewriting effects are best for Chinese.

Q: How do I get an API Key for /listenhub-tts?

Go to listenhub.ai to register and get an API Key, then set it as an environment variable: export LISTENHUB_API_KEY=your_key.

Q: What languages does /listenhub-tts support?

ListenHub supports voices for multiple languages including Chinese (zh) and English (en). When calling the voice list API, you can filter with the ?language=zh parameter.

Q: What diagram types does /insight-diagram support?

/insight-diagram supports 17 diagram types, including system architecture diagrams, 14 UML diagrams (class, object, component, deployment, package, composite structure, profile, use case, activity, state machine, sequence, communication, timing, interaction overview), flowcharts, and swimlane diagrams. Output is in HTML+SVG format, saved to the docs/ directory. Applicable to any software project.