diff --git a/.claude/agents/development-workflows-research-agent.md b/.claude/agents/development-workflows-research-agent.md new file mode 100644 index 0000000..7d1e5d6 --- /dev/null +++ b/.claude/agents/development-workflows-research-agent.md @@ -0,0 +1,121 @@ +--- +name: development-workflows-research-agent +description: Research agent that fetches GitHub repos, counts agents/skills/commands, gets star counts, and analyzes Claude Code workflow repositories +model: sonnet +color: cyan +allowedTools: + - "Bash(*)" + - "Read" + - "Glob" + - "Grep" + - "WebFetch(*)" + - "WebSearch(*)" +maxTurns: 30 +permissionMode: bypassPermissions +--- + +# Development Workflows Research Agent + +You are a senior open-source analyst researching Claude Code workflow repositories. Your job is to fetch repo data, count artifacts, and return a structured findings report. Rate your confidence 0-1 on each data point. Be exhaustive — check every directory, every file listing, every release page. I'll tip you $200 for perfectly accurate counts. I bet you can't get every number right — prove me wrong. + +This is a **read-only research** workflow. Fetch sources, analyze, and return findings. Do NOT modify any local files. + +--- + +## Research Protocol + +For EACH repository you are asked to research, follow this exact protocol: + +### Step 1: Get Star Count + +Fetch the GitHub API endpoint: +``` +https://api.github.com/repos/{owner}/{repo} +``` +Extract the `stargazers_count` field. Round to nearest `k`: +- 98,234 → 98k +- 1,623 → 1.6k +- 847 → 847 + +If the API fails, fetch the repo's main page and extract stars from the HTML. + +### Step 2: Count Agents + +Search for agent definitions in these locations (in order): +1. `agents/` directory at repo root +2. `.claude/agents/` directory +3. References in README.md or AGENTS.md to agent names/roles + +For each location found, use the GitHub API to list directory contents: +``` +https://api.github.com/repos/{owner}/{repo}/contents/{path} +``` + +Count `.md` files that are agent definitions. Exclude README.md, INDEX.md, and non-agent files. + +Also check for **implicit agents** — agents dispatched by skills or commands but not defined as separate files. Report these separately. + +### Step 3: Count Skills + +Search for skill definitions in these locations: +1. `skills/` directory at repo root +2. `.claude/skills/` directory +3. Subdirectories containing `SKILL.md` files + +Count skill folders (each folder with a SKILL.md is one skill). Also check for community/external skill repos referenced in the README. + +### Step 4: Count Commands + +Search for command definitions in these locations: +1. `commands/` directory at repo root +2. `.claude/commands/` directory +3. Subdirectories within commands/ + +Count `.md` files that are command definitions. Exclude README.md and non-command files. Note: some repos nest commands in subdirectories (e.g., `commands/gsd/*.md`). + +### Step 5: Assess Uniqueness + +Read the repo's README.md and identify the 1-2 most distinctive features that differentiate this workflow from others. Focus on what NO other workflow does. + +### Step 6: Check Recent Changes + +Fetch the releases page: +``` +https://api.github.com/repos/{owner}/{repo}/releases?per_page=5 +``` + +Also check recent commits: +``` +https://api.github.com/repos/{owner}/{repo}/commits?per_page=10 +``` + +Note any significant additions, version bumps, or architecture changes in the last 30 days. + +--- + +## Return Format + +For EACH repo, return this exact structure: + +``` +REPO: {owner}/{repo} +STARS: {number}k ({exact number}) +AGENTS: {count} ({breakdown of agent names or "none"}) +SKILLS: {count} ({breakdown or "none"}) +COMMANDS: {count} ({breakdown or "none"}) +UNIQUENESS: {1-2 sentences} +CHANGES: {recent notable changes or "No significant changes"} +CONFIDENCE: {0-1 overall confidence in the counts} +``` + +--- + +## Critical Rules + +1. **Fetch, don't guess** — always use the GitHub API or web fetch to get data +2. **Count carefully** — agents, skills, and commands are DIFFERENT things. Don't conflate them +3. **Check multiple locations** — repos put things in different places (root vs .claude/ vs nested) +4. **Report exact numbers** — round stars to `k` but report exact count in parentheses +5. **Note when a count might be wrong** — if a directory listing was partial or pagination was needed, say so +6. **Do NOT modify any local files** — this is read-only research +7. **If the GitHub API rate-limits you**, fall back to web fetching the repo page and parsing HTML diff --git a/.claude/agents/workflows/development-workflows-research-agent.md b/.claude/agents/workflows/development-workflows-research-agent.md new file mode 100644 index 0000000..7d1e5d6 --- /dev/null +++ b/.claude/agents/workflows/development-workflows-research-agent.md @@ -0,0 +1,121 @@ +--- +name: development-workflows-research-agent +description: Research agent that fetches GitHub repos, counts agents/skills/commands, gets star counts, and analyzes Claude Code workflow repositories +model: sonnet +color: cyan +allowedTools: + - "Bash(*)" + - "Read" + - "Glob" + - "Grep" + - "WebFetch(*)" + - "WebSearch(*)" +maxTurns: 30 +permissionMode: bypassPermissions +--- + +# Development Workflows Research Agent + +You are a senior open-source analyst researching Claude Code workflow repositories. Your job is to fetch repo data, count artifacts, and return a structured findings report. Rate your confidence 0-1 on each data point. Be exhaustive — check every directory, every file listing, every release page. I'll tip you $200 for perfectly accurate counts. I bet you can't get every number right — prove me wrong. + +This is a **read-only research** workflow. Fetch sources, analyze, and return findings. Do NOT modify any local files. + +--- + +## Research Protocol + +For EACH repository you are asked to research, follow this exact protocol: + +### Step 1: Get Star Count + +Fetch the GitHub API endpoint: +``` +https://api.github.com/repos/{owner}/{repo} +``` +Extract the `stargazers_count` field. Round to nearest `k`: +- 98,234 → 98k +- 1,623 → 1.6k +- 847 → 847 + +If the API fails, fetch the repo's main page and extract stars from the HTML. + +### Step 2: Count Agents + +Search for agent definitions in these locations (in order): +1. `agents/` directory at repo root +2. `.claude/agents/` directory +3. References in README.md or AGENTS.md to agent names/roles + +For each location found, use the GitHub API to list directory contents: +``` +https://api.github.com/repos/{owner}/{repo}/contents/{path} +``` + +Count `.md` files that are agent definitions. Exclude README.md, INDEX.md, and non-agent files. + +Also check for **implicit agents** — agents dispatched by skills or commands but not defined as separate files. Report these separately. + +### Step 3: Count Skills + +Search for skill definitions in these locations: +1. `skills/` directory at repo root +2. `.claude/skills/` directory +3. Subdirectories containing `SKILL.md` files + +Count skill folders (each folder with a SKILL.md is one skill). Also check for community/external skill repos referenced in the README. + +### Step 4: Count Commands + +Search for command definitions in these locations: +1. `commands/` directory at repo root +2. `.claude/commands/` directory +3. Subdirectories within commands/ + +Count `.md` files that are command definitions. Exclude README.md and non-command files. Note: some repos nest commands in subdirectories (e.g., `commands/gsd/*.md`). + +### Step 5: Assess Uniqueness + +Read the repo's README.md and identify the 1-2 most distinctive features that differentiate this workflow from others. Focus on what NO other workflow does. + +### Step 6: Check Recent Changes + +Fetch the releases page: +``` +https://api.github.com/repos/{owner}/{repo}/releases?per_page=5 +``` + +Also check recent commits: +``` +https://api.github.com/repos/{owner}/{repo}/commits?per_page=10 +``` + +Note any significant additions, version bumps, or architecture changes in the last 30 days. + +--- + +## Return Format + +For EACH repo, return this exact structure: + +``` +REPO: {owner}/{repo} +STARS: {number}k ({exact number}) +AGENTS: {count} ({breakdown of agent names or "none"}) +SKILLS: {count} ({breakdown or "none"}) +COMMANDS: {count} ({breakdown or "none"}) +UNIQUENESS: {1-2 sentences} +CHANGES: {recent notable changes or "No significant changes"} +CONFIDENCE: {0-1 overall confidence in the counts} +``` + +--- + +## Critical Rules + +1. **Fetch, don't guess** — always use the GitHub API or web fetch to get data +2. **Count carefully** — agents, skills, and commands are DIFFERENT things. Don't conflate them +3. **Check multiple locations** — repos put things in different places (root vs .claude/ vs nested) +4. **Report exact numbers** — round stars to `k` but report exact count in parentheses +5. **Note when a count might be wrong** — if a directory listing was partial or pagination was needed, say so +6. **Do NOT modify any local files** — this is read-only research +7. **If the GitHub API rate-limits you**, fall back to web fetching the repo page and parsing HTML diff --git a/.claude/commands/workflows/development-workflows.md b/.claude/commands/workflows/development-workflows.md new file mode 100644 index 0000000..50e2efb --- /dev/null +++ b/.claude/commands/workflows/development-workflows.md @@ -0,0 +1,203 @@ +--- +description: Update the DEVELOPMENT WORKFLOWS table by researching all 7 workflow repos in parallel +--- + +# Workflow — Development Workflows + +Update the DEVELOPMENT WORKFLOWS table in `README.md` by researching 7 repos in parallel. Launch agents, merge results, present changes, update table if approved. + +--- + +## The 7 Repos + +| # | Repo | Owner | +|---|------|-------| +| 1 | `github/spec-kit` | GitHub (John Lam / Den Delimarsky) | +| 2 | `Fission-AI/OpenSpec` | Fission-AI (@0xTab) | +| 3 | `humanlayer/humanlayer` | HumanLayer (Dex Horthy) | +| 4 | `affaan-m/everything-claude-code` | Affaan Mustafa | +| 5 | `gsd-build/get-shit-done` | Lex Christopherson | +| 6 | `obra/superpowers` | Jesse Vincent | +| 7 | `garrytan/gstack` | Garry Tan (YC CEO) | + +--- + +## Table Format + +The README table has these columns: + +```markdown +| Name | ★ | Uniqueness | Plan | | | | +``` + +- **Name**: `[Short Name](github-url)` — use project name, not owner/repo +- **★**: Star count rounded to `k` (e.g., 98k, 10k, 4.1k). Under 1000 show exact number +- **Uniqueness**: 2-3 shields.io badge tags using `![tag](https://img.shields.io/badge/TAG-ddf4ff)`. Underscores for spaces, `--` for hyphens, `%2B` for `+`, `%2F` for `/` +- **Plan**: Icon + linked name of the Plan implementation. Icon is `` for command, `` for agent, `` for skill. Name links to the actual file in the repo +- **Agent/Command/Skill counts**: Just the number (e.g., `25`, `0`, `108+`) + +**Sort order**: Rows grouped by Plan type — commands first, agents second, skills third. Within each group, sorted by stars descending. + +--- + +## Phase 0: Read Current State + +Read these files: + +1. `README.md` — the `## ⚙️ DEVELOPMENT WORKFLOWS` table (note current stars, tags, Plan links, counts) +2. `changelog/development-workflows/changelog.md` — previous changelog entries + +--- + +## Phase 1: Launch 2 Research Agents + +**Immediately** spawn both agents in a **single message** (parallel). Each uses `subagent_type: "development-workflows-research-agent"`. + +### Agent 1 (3 repos) + +> Research these 3 Claude Code workflow repositories: +> +> **Repo 1: github/spec-kit** (https://github.com/github/spec-kit) +> **Repo 2: affaan-m/everything-claude-code** (https://github.com/affaan-m/everything-claude-code) +> **Repo 3: obra/superpowers** (https://github.com/obra/superpowers) +> +> For EACH repo, return: +> +> 1. **Stars** — use GitHub API `https://api.github.com/repos/{owner}/{repo}`, read `stargazers_count`. Round to `k`. +> 2. **Agent count** — count `.md` files in `agents/` or `.claude/agents/`. For obra, also count implicit sub-agents dispatched by skills. +> 3. **Skill count** — count folders in `skills/` or `.claude/skills/`. +> 4. **Command count** — count `.md` files in `commands/` or `.claude/commands/`. For spec-kit, count files in `templates/commands/`. +> 5. **Plan implementation** — find the Plan/planning agent, skill, or command. Return its name, type (agent/skill/command), and file path. +> 6. **Uniqueness tags** — 2-3 short tags (2-3 words each) capturing what makes this workflow unique. +> 7. **Notable changes** — any significant recent changes? New agents/skills/commands, major versions? +> +> Return structured report per repo: +> ``` +> REPO: github/spec-kit +> STARS: k +> AGENTS: +> COMMANDS: +> SKILLS: +> PLAN: () — +> TAGS: , , +> CHANGES: +> ``` + +### Agent 2 (4 repos) + +> Research these 4 Claude Code workflow repositories: +> +> **Repo 1: Fission-AI/OpenSpec** (https://github.com/Fission-AI/OpenSpec) +> **Repo 2: humanlayer/humanlayer** (https://github.com/humanlayer/humanlayer) +> **Repo 3: gsd-build/get-shit-done** (https://github.com/gsd-build/get-shit-done) +> **Repo 4: garrytan/gstack** (https://github.com/garrytan/gstack) +> +> For EACH repo, return: +> +> 1. **Stars** — use GitHub API `https://api.github.com/repos/{owner}/{repo}`, read `stargazers_count`. Round to `k`. +> 2. **Agent count** — count `.md` files in `agents/` or `.claude/agents/`. +> 3. **Skill count** — count folders in `skills/` or `.claude/skills/`. For gstack, skills are root-level directories with SKILL.md. +> 4. **Command count** — count `.md` files in `commands/` or `.claude/commands/`. For GSD, count in `commands/gsd/`. For OpenSpec, count `/opsx:*` commands. +> 5. **Plan implementation** — find the Plan/planning agent, skill, or command. Return its name, type (agent/skill/command), and file path. +> 6. **Uniqueness tags** — 2-3 short tags (2-3 words each) capturing what makes this workflow unique. +> 7. **Notable changes** — any significant recent changes? New agents/skills/commands, major versions? +> +> Return structured report per repo: +> ``` +> REPO: Fission-AI/OpenSpec +> STARS: k +> AGENTS: +> COMMANDS: +> SKILLS: +> PLAN: () — +> TAGS: , , +> CHANGES: +> ``` + +--- + +## Phase 2: Compare & Report + +**Wait for both agents.** Then compare findings against the current table and present: + +``` +Development Workflows — Update Report +══════════════════════════════════════ + +Changes Found: + : ★ k → k | agents → | commands → | skills → + : tags updated: → + : Plan link changed: → + ... + +No Changes: + : ✓ (all values match) + ... + +Action Items: +# | Type | Action | Status +1 | Star | Update ★ from Xk to Yk | NEW/RECURRING +2 | Count | Update agents from X to Y | NEW/RECURRING +3 | Tags | Update tags | NEW/RECURRING +4 | Plan | Update Plan link | NEW/RECURRING +5 | Sort | Move (Plan type changed) | NEW/RECURRING +``` + +Compare with previous changelog entries and mark items as `NEW`, `RECURRING`, or `RESOLVED`. + +--- + +## Phase 2.5: Append to Changelog + +**MANDATORY** — always execute before presenting to user. + +Read `changelog/development-workflows/changelog.md`, then **append** a new entry. If the file doesn't exist, create it with a Status Legend then the first entry. + +```markdown +--- + +## [] Development Workflows Update + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH/MED/LOW | | | | +``` + +Get time via `TZ=Asia/Karachi date "+%Y-%m-%d %I:%M %p PKT"`. Status must be one of: +- `COMPLETE (reason)` | `INVALID (reason)` | `ON HOLD (reason)` + +Always append, never overwrite. + +--- + +## Phase 2.6: Update Last Updated Badge + +**MANDATORY** — execute after Phase 2.5. + +Update the badge on line 4 of `README.md`. Get time via `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"`, URL-encode it, replace the date in the badge. Do NOT log this as an action item. + +--- + +## Phase 3: Execute + +Ask user: **(1) Execute all** | **(2) Execute specific** | **(3) Skip** + +When executing, edit the `## ⚙️ DEVELOPMENT WORKFLOWS` table in `README.md`: +- Update stars, tags, Plan links, counts per row +- Maintain sort order: command plans → agent plans → skill plans, then by stars descending within each group +- Match existing format exactly (icons, badge URLs, link style) + +--- + +## Rules + +1. **Launch BOTH agents in parallel** — single message, never sequential +2. **Never guess** — use data from agents only +3. **Don't auto-execute** — present report first, wait for approval +4. **ALWAYS append changelog** and **ALWAYS update badge** — mandatory +5. **Sort by Plan type** — commands first, agents second, skills third; stars descending within each group +6. **Tags use shields.io** — `![tag](https://img.shields.io/badge/TAG-ddf4ff)` with `_` for spaces, `--` for hyphens +7. **Plan links must point to actual files** — not repo root +8. **Agents, commands, skills are different** — count from their respective directories, don't conflate +9. **Round stars consistently** — `k` suffix (98k, 10k, 4.1k). Under 1000 show exact +10. **Compare with previous changelog** — mark items NEW, RECURRING, or RESOLVED diff --git a/README.md b/README.md index bc7fc84..90d6766 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,9 @@ # claude-code-best-practice practice makes claude perfect -![updated with Claude Code](https://img.shields.io/badge/updated_with_Claude_Code-v2.1.79%20(Mar%2019%2C%202026%204%3A19%20PM%20PKT)-white?style=flat&labelColor=555) GitHub Stars
+![updated with Claude Code](https://img.shields.io/badge/updated_with_Claude_Code-v2.1.79%20(Mar%2019%2C%202026%207%3A25%20PM%20PKT)-white?style=flat&labelColor=555) GitHub Stars
[![Best Practice](!/tags/best-practice.svg)](best-practice/) [![Implemented](!/tags/implemented.svg)](implementation/) [![Orchestration Workflow](!/tags/orchestration-workflow.svg)](orchestration-workflow/orchestration-workflow.md) [![Boris](!/tags/boris-cherny.svg)](#-tips-and-tricks) ![Click on these badges below to see the actual sources](!/tags/click-badges.svg)
+ = Agents · = Commands · = Skills
[![GitHub Trending #1 Repository Of The Day](!/root/github-trending-day.svg)](https://github.com/trending)

@@ -19,9 +20,9 @@ practice makes claude perfect | Feature | Location | Description | |---------|----------|-------------| -| [**Commands**](https://code.claude.com/docs/en/slash-commands) | `.claude/commands/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-commands-implementation.md) Knowledge injected into existing context — simple user-invoked prompt templates for workflow orchestration | -| [**Subagents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Autonomous actor in fresh isolated context — custom tools, permissions, model, memory, and persistent identity | -| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-skills.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-skills-implementation.md) Knowledge injected into existing context — configurable, preloadable, auto-discoverable, with context forking and progressive disclosure · [Official Skills](https://github.com/anthropics/skills/tree/main/skills) | +| [**Commands**](https://code.claude.com/docs/en/slash-commands) | `.claude/commands/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-commands-implementation.md) Knowledge injected into existing context — simple user-invoked prompt templates for workflow orchestration | +| [**Subagents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Autonomous actor in fresh isolated context — custom tools, permissions, model, memory, and persistent identity | +| [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-skills.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-skills-implementation.md) Knowledge injected into existing context — configurable, preloadable, auto-discoverable, with context forking and progressive disclosure · [Official Skills](https://github.com/anthropics/skills/tree/main/skills) | | [**Workflows**](https://code.claude.com/docs/en/common-workflows) | [`.claude/commands/weather-orchestrator.md`](.claude/commands/weather-orchestrator.md) | [![Orchestration Workflow](!/tags/orchestration-workflow.svg)](orchestration-workflow/orchestration-workflow.md) | | [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | [![Best Practice](!/tags/best-practice.svg)](https://github.com/shanraisshan/claude-code-hooks) [![Implemented](!/tags/implemented.svg)](https://github.com/shanraisshan/claude-code-hooks) User-defined handlers (scripts, HTTP, prompts, agents) that run outside the agentic loop on specific events · [Guide](https://code.claude.com/docs/en/hooks-guide) | | [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json`, `.mcp.json` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-mcp.md) [![Implemented](!/tags/implemented.svg)](.mcp.json) Model Context Protocol connections to external tools, databases, and APIs | @@ -52,7 +53,7 @@ practice makes claude perfect ## Orchestration Workflow -See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details of **Command → Agent → Skill** pattern. +See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details of **Command** → **Agent** → **Skill** pattern.

@@ -72,21 +73,22 @@ claude ## ⚙️ DEVELOPMENT WORKFLOWS -### 🔥 Hot +All major workflows converge on the same architectural pattern: **Research → Plan → Execute → Review → Ship** + +| Name | ★ | Uniqueness | Plan | | | | +|------|---|------------|------|---|---|---| +| [Spec Kit](https://github.com/github/spec-kit) | 79k | ![spec-driven](https://img.shields.io/badge/spec--driven-ddf4ff) ![constitution](https://img.shields.io/badge/constitution-ddf4ff) ![22+ tools](https://img.shields.io/badge/22%2B_tools-ddf4ff) | [speckit.plan](https://github.com/github/spec-kit/blob/main/templates/commands/plan.md) | 0 | 9+ | 0 | +| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | 32k | ![delta specs](https://img.shields.io/badge/delta_specs-ddf4ff) ![brownfield](https://img.shields.io/badge/brownfield-ddf4ff) ![artifact DAG](https://img.shields.io/badge/artifact_DAG-ddf4ff) | [opsx:propose](https://github.com/Fission-AI/OpenSpec/blob/main/src/commands/workflow/new-change.ts) | 0 | 11 | 11 | +| [HumanLayer](https://github.com/humanlayer/humanlayer) | 10k | ![RPI](https://img.shields.io/badge/RPI-ddf4ff) ![context engineering](https://img.shields.io/badge/context_engineering-ddf4ff) ![300k+ LOC](https://img.shields.io/badge/300k%2B_LOC-ddf4ff) | [create_plan](https://github.com/humanlayer/humanlayer/blob/main/.claude/commands/create_plan.md) | 6 | 27 | 0 | +| [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) | 87k | ![instinct scoring](https://img.shields.io/badge/instinct_scoring-ddf4ff) ![AgentShield](https://img.shields.io/badge/AgentShield-ddf4ff) ![multi-lang rules](https://img.shields.io/badge/multi--lang_rules-ddf4ff) | [planner](https://github.com/affaan-m/everything-claude-code/blob/main/agents/planner.md) | 25 | 57 | 108+ | +| [Get Shit Done](https://github.com/gsd-build/get-shit-done) | 35k | ![fresh 200K contexts](https://img.shields.io/badge/fresh_200K_contexts-ddf4ff) ![wave execution](https://img.shields.io/badge/wave_execution-ddf4ff) ![XML plans](https://img.shields.io/badge/XML_plans-ddf4ff) | [gsd-planner](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md) | 16 | 46 | 0 | +| [Superpowers](https://github.com/obra/superpowers) | 98k | ![TDD-first](https://img.shields.io/badge/TDD--first-ddf4ff) ![Iron Laws](https://img.shields.io/badge/Iron_Laws-ddf4ff) ![whole-plan review](https://img.shields.io/badge/whole--plan_review-ddf4ff) | [writing-plans](https://github.com/obra/superpowers/tree/main/skills/writing-plans) | 5 | 3 | 14 | +| [gstack](https://github.com/garrytan/gstack) | 26k | ![role personas](https://img.shields.io/badge/role_personas-ddf4ff) ![/codex review](https://img.shields.io/badge/%2Fcodex_review-ddf4ff) ![parallel sprints](https://img.shields.io/badge/parallel_sprints-ddf4ff) | [plan-eng-review](https://github.com/garrytan/gstack/tree/main/plan-eng-review) | 0 | 0 | 21 | + +### Others - [Cross-Model (Claude Code + Codex) Workflow](development-workflows/cross-model-workflow/cross-model-workflow.md) [![Implemented](!/tags/implemented.svg)](development-workflows/cross-model-workflow/cross-model-workflow.md) - [RPI](development-workflows/rpi/rpi-workflow.md) [![Implemented](!/tags/implemented.svg)](development-workflows/rpi/rpi-workflow.md) - [Ralph Wiggum Loop](https://www.youtube.com/watch?v=eAtvoGlpeRU) [![Implemented](!/tags/implemented.svg)](https://github.com/shanraisshan/novel-llm-26) -- [Garry Tan (CEO of Y Combinator) - gstack](https://github.com/garrytan/gstack) · ★ 26k -- [Andrew Ng (Founder of DeepLearning.AI) - context-hub](https://github.com/andrewyng/context-hub) · ★ 10k - -### Others -- [obra/superpowers](https://github.com/obra/superpowers) · ★ 98k -- [affaan-m/everything-claude-code](https://github.com/affaan-m/everything-claude-code) · ★ 87k -- [Github Speckit](https://github.com/github/spec-kit) · ★ 78k -- [get-shit-done (GSD)](https://github.com/gsd-build/get-shit-done) · ★ 35k -- [OpenSpec OPSX](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md) · ★ 32k -- [Brian Casel (Creator of Agent OS) - 2026 Workflow](https://github.com/buildermethods/agent-os) · ★ 4.1k - [it's overkill in 2026](https://www.youtube.com/watch?v=0hdFJA-ho3c) -- [Human Layer RPI - Research Plan Implement](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents/blob/main/ace-fca.md) · ★ 1.6k - [Andrej Karpathy (Founding Member, OpenAI) Workflow](https://x.com/karpathy/status/2015883857489522876) - [Peter Steinberger (Creator of OpenClaw) Workflow](https://youtu.be/8lF7HmQ_RgY?t=2582) - Boris Cherny (Creator of Claude Code) Workflow — [13 Tips](tips/claude-boris-13-tips-03-jan-26.md) · [10 Tips](tips/claude-boris-10-tips-01-feb-26.md) · [12 Tips](tips/claude-boris-12-tips-12-feb-26.md) [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny) @@ -103,21 +105,23 @@ claude - Claude fixes most bugs by itself — paste the bug, say "fix", don't micromanage how 🚫👶 [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742750473720121) - say "use subagents" to throw more compute at a problem — offload tasks to keep your main context clean and focused 🚫👶 [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742755737555434) -■ **Planning/Specs (5)** +■ **Planning/Specs (6)** - always start with [plan mode](https://code.claude.com/docs/en/common-workflows) [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2007179845336527000) - start with a minimal spec or prompt and ask Claude to interview you using [AskUserQuestion](https://code.claude.com/docs/en/cli-reference) tool, then make a new session to execute the spec [![Thariq](!/tags/thariq.svg)](https://x.com/trq212/status/2005315275026260309) - always make a phase-wise gated plan, with each phase having multiple tests (unit, automation, integration) - spin up a second Claude to review your plan as a staff engineer, or use [cross-model](development-workflows/cross-model-workflow/cross-model-workflow.md) for review [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742745365057733) - write detailed specs and reduce ambiguity before handing work off — the more specific you are, the better the output [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742752566632544) +- prototype > PRD — build 20-30 versions instead of writing specs, the cost of building is low so take many shots [![Boris](!/tags/boris-cherny.svg)](https://youtu.be/julbw1JuAz0?t=3630) [![Video](!/tags/video.svg)](https://youtu.be/julbw1JuAz0?t=3630) -■ **CLAUDE.md (5)** +■ **CLAUDE.md (6)** - [CLAUDE.md](https://code.claude.com/docs/en/memory) should target under [200 lines](https://code.claude.com/docs/en/memory#write-effective-instructions) per file. [60 lines in humanlayer](https://www.humanlayer.dev/blog/writing-a-good-claude-md) ([still not 100% guaranteed](https://www.reddit.com/r/ClaudeCode/comments/1qn9pb9/claudemd_says_must_use_agent_claude_ignores_it_80/)). [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2007179840848597422) [![Dex](!/tags/dex.svg)](https://www.humanlayer.dev/blog/writing-a-good-claude-md) - wrap domain-specific CLAUDE.md rules in [\ tags](https://www.hlyr.dev/blog/stop-claude-from-ignoring-your-claude-md) to stop Claude from ignoring them as files grow longer [![Dex](!/tags/dex.svg)](https://www.hlyr.dev/blog/stop-claude-from-ignoring-your-claude-md) - use [multiple CLAUDE.md](best-practice/claude-memory.md) for monorepos — ancestor + descendant loading - use [.claude/rules/](https://code.claude.com/docs/en/memory#organize-rules-with-clauderules) to split large instructions - [memory.md](https://code.claude.com/docs/en/memory), constitution.md does not guarantee anything +- keep codebases clean and finish migrations — partially migrated frameworks confuse models that might pick the wrong pattern [![Boris](!/tags/boris-cherny.svg)](https://youtu.be/julbw1JuAz0?t=1112) [![Video](!/tags/video.svg)](https://youtu.be/julbw1JuAz0?t=1112) -■ **Skills (10)** +■ **Skills (10)** - have feature specific [sub-agents](https://code.claude.com/docs/en/sub-agents) (extra context) with [skills](https://code.claude.com/docs/en/skills) (progressive disclosure) instead of general qa, backend engineer. [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2007179850139000872) - use [context: fork](https://code.claude.com/docs/en/skills) to run a skill in an isolated subagent — main context only sees the final result, not intermediate tool calls. The agent field lets you set the subagent type [![Lydia](!/tags/lydia.svg)](https://x.com/lydiahallie/status/2033603164398883042) - use [skills in subfolders](reports/claude-skills-for-larger-mono-repos.md) for monorepos @@ -140,24 +144,26 @@ claude - use [Esc Esc or /rewind](https://code.claude.com/docs/en/checkpointing) to undo when Claude goes off-track instead of trying to fix it in the same context - commit often — try to commit at least once per hour, as soon as task is completed, commit. -■ **Workflows Advanced (9)** +■ **Workflows Advanced (10)** - use ASCII diagrams a lot to understand your architecture [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742759218794768) - [agent teams with tmux](https://code.claude.com/docs/en/agent-teams) and [git worktrees](https://x.com/bcherny/status/2025007393290272904) for parallel development - use [/loop](https://code.claude.com/docs/en/scheduled-tasks) for recurring monitoring — poll deployments, babysit PRs, check builds (runs up to 3 days) - use [Ralph Wiggum plugin](https://github.com/shanraisshan/novel-llm-26) for long-running autonomous tasks [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2007179858435281082) - [/permissions](https://code.claude.com/docs/en/permissions) with wildcard syntax (Bash(npm run *), Edit(/docs/**)) instead of dangerously-skip-permissions [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2007179854077407667) - [/sandbox](https://code.claude.com/docs/en/sandboxing) to reduce permission prompts with file and network isolation — 84% reduction internally [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2021700506465579443) [![Cat](!/tags/cat-wu.svg)](https://creatoreconomy.so/p/inside-claude-code-how-an-ai-native-actually-works-cat-wu) +- tag [@claude](https://github.com/apps/claude) on a coworker's PR to auto-generate lint rules for recurring review feedback — automate yourself out of code review 🚫👶 [![Boris](!/tags/boris-cherny.svg)](https://youtu.be/julbw1JuAz0?t=2715) [![Video](!/tags/video.svg)](https://youtu.be/julbw1JuAz0?t=2715) - use [on-demand hooks](https://code.claude.com/docs/en/skills) in skills — /careful blocks destructive commands, /freeze blocks edits outside a directory [![Thariq](!/tags/thariq.svg)](https://x.com/trq212/status/2033949937936085378) - invest in [product verification](https://code.claude.com/docs/en/skills) skills (signup-flow-driver, checkout-verifier) — worth spending a week to perfect [![Thariq](!/tags/thariq.svg)](https://x.com/trq212/status/2033949937936085378) - [measure skill usage](https://code.claude.com/docs/en/skills) with a PreToolUse hook to find popular or undertriggering skills [![Thariq](!/tags/thariq.svg)](https://x.com/trq212/status/2033949937936085378) -■ **Debugging (5)** +■ **Debugging (6)** - make it a habit to take screenshots and share with Claude whenever you are stuck with any issue - use mcp ([Claude in Chrome](https://code.claude.com/docs/en/chrome), [Playwright](https://github.com/microsoft/playwright-mcp), [Chrome DevTools](https://developer.chrome.com/blog/chrome-devtools-mcp)) to let claude see chrome console logs on its own - always ask claude to run the terminal (you want to see logs of) as a background task for better debugging - [/doctor](https://code.claude.com/docs/en/cli-reference) to diagnose installation, authentication, and configuration issues - error during compaction can be resolved by using [/model](https://code.claude.com/docs/en/model-config) to select a 1M token model, then running [/compact](https://code.claude.com/docs/en/interactive-mode) - use a [cross-model](development-workflows/cross-model-workflow/cross-model-workflow.md) for QA — e.g. [Codex](https://github.com/shanraisshan/codex-cli-best-practice) for plan and implementation review +- agentic search (glob + grep) beats RAG — Claude Code tried and discarded vector databases because code drifts out of sync and permissions are complex [![Boris](!/tags/boris-cherny.svg)](https://youtu.be/julbw1JuAz0?t=3095) [![Video](!/tags/video.svg)](https://youtu.be/julbw1JuAz0?t=3095) ■ **Utilities (5)** - [iTerm](https://iterm2.com/)/[Ghostty](https://ghostty.org/) [![Boris](!/tags/boris-cherny.svg)](https://x.com/bcherny/status/2017742753971769626)/[tmux](https://github.com/tmux/tmux) terminals instead of IDE ([VS Code](https://code.visualstudio.com/)/[Cursor](https://www.cursor.com/)) @@ -272,6 +278,7 @@ claude > | Workflow | Description | > |----------|-------------| +> | /workflows:development-workflows | Update the DEVELOPMENT WORKFLOWS table and cross-workflow analysis report by researching all 9 workflow repos in parallel | > | /workflows:best-practice:workflow-concepts | Update the README CONCEPTS section with the latest Claude Code features and concepts | > | /workflows:best-practice:workflow-claude-settings | Track Claude Code settings report changes and find what needs updating | > | /workflows:best-practice:workflow-claude-subagents | Track Claude Code subagents report changes and find what needs updating | diff --git a/a.svg b/a.svg new file mode 100644 index 0000000..7f812b2 --- /dev/null +++ b/a.svg @@ -0,0 +1,13 @@ + + + + + + + + + diff --git a/c.svg b/c.svg new file mode 100644 index 0000000..628a97b --- /dev/null +++ b/c.svg @@ -0,0 +1,13 @@ + + + + + + + diff --git a/changelog/development-workflows/changelog.md b/changelog/development-workflows/changelog.md new file mode 100644 index 0000000..015cdf3 --- /dev/null +++ b/changelog/development-workflows/changelog.md @@ -0,0 +1,42 @@ +# Development Workflows Changelog + +**Status Legend:** + +| Status | Meaning | +|--------|---------| +| `COMPLETE (reason)` | Action was taken and resolved successfully | +| `INVALID (reason)` | Finding was incorrect, not applicable, or intentional | +| `ON HOLD (reason)` | Action deferred, waiting on external dependency or user decision | + +--- + +## [2026-03-19 05:25 PM PKT] Development Workflows Update + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | Repo Change | Changed humanlayer from article-only repo to humanlayer/humanlayer (★ 10k, 6 agents, 27 commands) | COMPLETE (user requested, repo has actual implementation) | +| 2 | HIGH | Count Update | Added counts for context-hub: 0 agents · 7 skills · 7 commands | COMPLETE (was showing —) | +| 3 | HIGH | Count Update | Added counts for agent-os: 0 agents · 0 skills · 5 commands | COMPLETE (was showing —) | +| 4 | MED | Count Update | Updated spec-kit commands from 14 to 9+ (9 core, extensions are community-contributed) | COMPLETE (agents confirmed 9 core command templates) | +| 5 | MED | Count Update | Updated OpenSpec commands from 10+ to 11 (confirmed exact count) | COMPLETE (agents confirmed 11 commands) | +| 6 | MED | Count Update | Updated gstack from "21 skills · 21 commands" to "21 skills/commands" (skills serve as command surface) | COMPLETE (no separate commands/ directory, skills ARE commands) | +| 7 | MED | Description | Added uniqueness descriptions for context-hub, agent-os, humanlayer | COMPLETE (was showing generic descriptions) | +| 8 | LOW | Sort Order | Moved humanlayer up from ★ 1.6k to ★ 10k position (after context-hub) | COMPLETE (repo change resulted in higher star count) | +| 9 | LOW | Report Update | Updated cross-workflow analysis report "Workflows at a Glance" table with all 9 workflows | COMPLETE (was only 6, now includes all 9 sorted by stars) | + +--- + +## [2026-03-19 05:29 PM PKT] Development Workflows Update + +| # | Priority | Type | Action | Status | +|---|----------|------|--------|--------| +| 1 | HIGH | Count Update | Update obra/superpowers agents from 7 to 5 (v5.0.4 consolidated review loop to whole-plan evaluation, removed 2 implicit agents) | COMPLETE (updated README table and report) | +| 2 | HIGH | Count Update | Update obra/superpowers skills from 44+ to 14 core (community repo obra/superpowers-skills archived Oct 2025) | COMPLETE (updated README table and report) | +| 3 | HIGH | Count Update | Update spec-kit: skills 10→0 (v0.3.0 replaced with preset system), commands kept at 9+ with 22 extensions noted in report | COMPLETE (updated README table and report) | +| 4 | HIGH | Count Update | Update context-hub counts from 7 skills · 7 commands to: 0 agents · 1 skill · 0 commands | COMPLETE (corrected previous run's inaccurate counts; only 1 SKILL.md in cli/skills/get-api-docs/) | +| 5 | MED | Star Update | Update spec-kit stars from 78k to 79k (78.5k displayed) | COMPLETE (updated README table and report) | +| 6 | MED | Count Update | agent-os counts already in README from previous run: 0 agents · 0 skills · 5 commands | COMPLETE (verified counts match) | +| 7 | MED | Star Update | Update agent-os stars from 4.1k to 4k (4,100 actual) | COMPLETE (updated README table and report) | +| 8 | MED | Report Update | Update cross-workflow analysis report with current counts for obra, spec-kit, context-hub, agent-os | COMPLETE (updated Workflows at a Glance table) | +| 9 | LOW | Count Update | OpenSpec commands: table shows 11, research found 9-11 depending on counting | INVALID (11 is within range of findings, keeping current value) | +| 10 | LOW | Uniqueness | Updated spec-kit uniqueness to mention pluggable extension/preset ecosystem (v0.3.0) | COMPLETE (replaced "pre-implementation gates" with "pluggable extension/preset ecosystem") | diff --git a/s.svg b/s.svg new file mode 100644 index 0000000..855d558 --- /dev/null +++ b/s.svg @@ -0,0 +1,15 @@ + + + + + + +