Skip to content

About

Portable Claude Code workflow: rules, skills, hooks, agents — devcontainer + Codespaces ready

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

pipelinekit

License: MIT Latest tag CI

Autonomous orchestrator for Claude Code. Write a one-line feature description; pipelinekit ships a merged PR. Charter → Analyze → Plan → Implement → Review → Merge, all driven by multi-agent dispatch with no human in the loop unless you opt in.

⚠️ v0.0.1 — pre-release. Actively developed; API not yet stable. Pin to a specific commit SHA when integrating into your own workflows.

Troubleshooting

Stuck on install or a first run? See documentation/getting-started.html#troubleshooting for the most common failure modes (/pipeline not found after install, cloud-provider CLI auth halts, review cycles not converging, a skill not firing).


Read the docs

The complete documentation lives in documentation/. Every page is a single self-contained HTML file — no CDN, no remote assets, no build step. After cloning, open any page directly via file:// URL:

xdg-open documentation/index.html    # Linux
open documentation/index.html         # macOS
start documentation/index.html        # Windows / WSL

Or download just the documentation/ folder as a zip and open index.html — same result, no clone needed.

Start with the master guide: documentation/getting-started.html — install + 4 worked tutorials (hello-world, TDD, Vercel deploy, meta-walkthrough).


What pipelinekit gives you

  • 45 skills + 22 agents + 32 hooks wired together so /pipeline can take a feature from charter to merged PR without intervention.
  • 5 cloud deployment providers (Azure, Vercel, Railway, Render, DigitalOcean) on a shared deployment-engineer.md base. Your charter selects one; /pipeline routes deployment automatically.
  • Sandbox-isolated execution (default-on) — every subprocess in a podman/docker/worktree sandbox with auto-detected provider chain. Engine-when-present: prefer podman, else docker, else graceful fallback to worktree-only with a one-line stderr log. Opt out per run via SANDBOX_PROVIDER=worktree-only or PIPELINE_NO_SANDBOX=1.
  • TDD doctrine baked in — dev-class features auto-route through tdd-test-writer → tdd-implementer for red/green pairing, enforced by tdd-red-phase-gate.sh hook.
  • Multi-agent /pipeline-review — 2–6 specialized review agents (code-reviewer, security-auditor, test-engineer, performance-tuner, spec-tracer, symbol-verifier) with charter-aware finding classification + Path A/B/M/N routing.
  • Research loop — Karpathy-style autoresearch via /research: hypothesize → mutate → benchmark → keep-or-reset, with optional auto-publish to a branch via /ppr --research.
  • GitHub-native — --issues mode pulls features from open issues; PR bodies auto-include Closes #N; squash-merge via gh pr merge --squash --auto.

Quick install

Local (any Linux / WSL / macOS bash)

git clone https://github.com/Bruce188/pipelinekit.git
cd pipelinekit
./scripts/install.sh

install.sh is idempotent. Re-run to update.

Cloud cold-start (Oracle / Hetzner)

# Oracle Cloud Free Tier ARM A1 (aarch64, 24 GB RAM):
curl -fsSL https://raw.githubusercontent.com/Bruce188/pipelinekit/main/scripts/cloud/oracle-bootstrap.sh | bash

# Hetzner CX22 (x86_64, 4 GB RAM — swap auto-created):
curl -fsSL https://raw.githubusercontent.com/Bruce188/pipelinekit/main/scripts/cloud/hetzner-bootstrap.sh | bash

Both scripts are idempotent. Secrets read from env, never baked in. Full walkthrough: documentation/cloud-setup.html.

GitHub Codespaces

Open the repo in Codespaces — the devcontainer post-create runs install.sh automatically. Then claude in the terminal to start.

Add to an existing Claude Code session

"Clone https://github.com/Bruce188/pipelinekit.git into ~/work,
 cd into it, and run ./scripts/install.sh non-interactively."

Full install variants (local, cloud cold-start, Codespaces / devcontainer, non-interactive): documentation/installation.html.


First run

After install, drop a feature file in a target repo:

mkdir -p docs
cat > docs/features.md <<'EOF'
## fix/readme-typo

**Description:** Fix the typo in README.md where "occured" should be "occurred".

**Constraints:** Single-file edit. No new tests. Non-dev feature class.

### Run Log
EOF

claude

In the Claude session:

/pipeline docs/features.md --no-charter

That's it. The orchestrator handles the rest: analyze → plan → branch → implement → review → push → PR → squash-merge. Watch state transitions in real time. Total runtime: ~3–5 minutes for a typo fix; ~15–30 minutes for a real feature.

Full tutorial set: documentation/getting-started.html.


Pipeline modes

/pipeline routes per feature based on <type>/<name> prefix in docs/features.md:

Prefix Mode TDD
feat, fix, refactor, perf, test dev yes — tdd-test-writer → tdd-implementer
docs, chore, style, build, ci, content, ops, research non-dev skipped

Override with **Type:** dev|non-dev per-feature.


What's inside

Layer Contents
Rules claude/CLAUDE.md.template, claude/rules/workflow.md, claude/rules/agents-worktrees.md
Skills (45) pipeline, analyze, create-plan, implement-plan, pipeline-review, ppr, research, tdd, incident, landing-report, learn, azure-ops, vercel-ops, railway-ops, render-ops, digitalocean-ops, expo, ios, docs-writer, document-release, claude-md-enhancer, write-a-skill, zoom-out, simplify, caveman-mode, ...
Agents (22) code-reviewer, security-auditor, symbol-verifier, spec-tracer, tdd-test-writer, tdd-implementer, mobile-dev, deployment-engineer (base), azure-deployment-engineer, vercel-deployment-engineer, railway-deployment-engineer, render-deployment-engineer, digitalocean-deployment-engineer, incident-responder, claude-md-guardian, ...
Hooks (32) validate-commit-msg, strip-ai-attribution, block-push-main, block-stage-sensitive, block-dangerous-commands, tdd-order-check, tdd-red-phase-gate, claude-md-guard, env-scrub, notify-emit, context-warning, context-budget-advisor, verify-worktree-commit, ...
MCP context7, serena, sequential-thinking, agentmemory, codegraph, graphify, optional local-rag + claude-context
LSP pyright, typescript, csharp, gopls, rust-analyzer
Model overlays Per-model tuning for opus-4-7, sonnet-4-6, haiku-4-5 (consumed by phase skills)
Host adapters claude + codex (concrete), cursor/gemini (stubs) — interface scaffold for multi-host dispatch
Sandbox Pluggable SandboxProvider.sh (auto default: podman → docker → worktree-only) with sandbox_wrap shared helper

Cloud deployment

Five providers, all driven from Charter Topic 10:

Agent Skill Provider Guide
@azure-deployment-engineer azure-ops Azure App Service / Container Apps / Function Apps / AKS docs
@vercel-deployment-engineer vercel-ops Vercel (Next.js / SvelteKit / Astro / Remix) docs
@railway-deployment-engineer railway-ops Railway (zero-Dockerfile container PaaS) docs
@render-deployment-engineer render-ops Render (managed container PaaS) docs
@digitalocean-deployment-engineer digitalocean-ops DigitalOcean App Platform docs

claude/agents/deployment-engineer.md is the shared base agent (dispatch with provider: <name>) describing the shared contract (auth posture, secret hygiene, health-check polling, no-direct-REST). Each named agent extends it for its provider.


/ppr --research

Publish research keep-rows from a TSV to a dedicated branch. Dry-run by default; pass --no-dry-run to publish:

/ppr --research                          # dry-run (default)
/ppr --research --no-dry-run --research-tag my-experiment

Reference: documentation/ppr-research-flag.html.


Layout

pipelinekit/
├── .devcontainer/         # Codespaces / VS Code devcontainer
├── claude/                # Overlay installed to ~/.claude/
│   ├── CLAUDE.md.template
│   ├── rules/
│   ├── skills/            # 45 native skills
│   │   ├── pipeline/      # The autonomous orchestrator
│   │   ├── docs-writer/   # template.html + render.py (rich-template HTML)
│   │   ├── research/      # Karpathy autoresearch loop + tsv-viewer.sh
│   │   ├── {railway,render,digitalocean}-ops/  # Cloud provider ops skills
│   │   └── ...
│   ├── agents/            # 22 specialized agents (incl. deployment-engineer base)
│   ├── hooks/             # 32 production hooks (29 harness + 3 git)
│   ├── lib/
│   │   ├── pipeline/      # ac_lint, charter_revalidate, decomposition_check, ...
│   │   └── sandbox/       # SandboxProvider.sh + providers/ + sandbox_wrap.sh
│   ├── model-overlays/    # opus-4-7.md, sonnet-4-6.md, haiku-4-5.md, claude.md
│   ├── host-adapters/     # claude.sh + codex.sh (concrete), cursor.sh / gemini.sh (stubs)
│   ├── memory/            # MEMORY.md scaffold (empty by design; populated per project)
│   └── config/            # never-stage.txt, etc.
├── scripts/
│   ├── install.sh         # Idempotent installer
│   ├── sandbox/           # Container base image (Containerfile + build.sh)
│   └── cloud/             # Oracle + Hetzner bootstrap scripts
├── documentation/         # User-facing docs — all self-contained HTML
│   ├── index.html         # Landing page
│   ├── getting-started.html  # Master guide (start here)
│   ├── changelog.html     # v0.0.1 dev log
│   ├── installation.html, pipeline.html, cloud-setup.html
│   ├── deployment-{azure,vercel,railway,render,digitalocean}.html
│   └── SKILL-AUTHORING-STANDARD.html, SKILL_PIPELINE.html, NOTICE.html  # Vendored reference standards + attribution
├── .mcp.json.template     # MCP server config (copy to project root on install)
├── LICENSE                # MIT
└── README.md

Note: docs/ is intentionally NOT in the repo tree above — it's gitignored and exclusively for AI-workflow artifacts (analysis-vN.md, plan-vN.md, prompts-vN.md, review-vN.md, charter.md, progress.md, pipeline-state.md, features-vN.md, etc.). User-facing docs live in documentation/ and are committed as HTML.


Caveman mode (wenyan-ultra)

Default verbosity in pipelinekit sessions: caveman wenyan-ultra. Drops articles, filler, hedging. Code, commits, and security-critical text remain normal English.

/caveman lite | full | ultra
stop caveman     # revert to normal

Memory

Memory ships as an empty scaffold. After install, the agentmemory MCP (registered by install.sh) is the canonical memory store; legacy flat files under ~/.claude/projects/<project-slug>/memory/ stay read-only as a rollback window (dual-write via PIPELINE_KEEP_FLAT_FILE_MEMORY=1). See claude/memory/MEMORY.md for the flat-file schema reference (recency-weighted confidence decay, four memory types: user / feedback / project / reference).


Reference


Credits

Pipelinekit stands on the shoulders of several upstream projects, plus inspiration from individual researchers and the Claude platform itself.

Inspirational-but-not-vendored:

  • Andrej Karpathy — the autoresearch-loop pattern (hypothesize → mutate one file → benchmark → keep-or-reset → append row → repeat) is the design behind /research. The symbol-verifier anti-hallucination agent (Agent 6 of /pipeline-review on medium+ diffs) is inspired by the same first-principles verification ethos.
  • Anthropic — the entire runtime: Claude Code, the Agent SDK, multi-agent dispatch, Skills, Hooks, MCP, PushNotification, and the underlying Claude models that every pipelinekit phase calls. Pipelinekit is a workflow overlay on Claude Code — without Anthropic's platform, there's no pipelinekit.

Vendored upstreams (full table with pinned SHAs + licenses + scope + re-vendor procedures at documentation/credits.html):

Per-directory NOTICE.md files carry the full upstream license text and re-vendor procedures.


License

MIT. See LICENSE. Pipelinekit's own original code (orchestrator, hooks, docs-writer, install scripts, documentation) is MIT-licensed; vendored upstream files retain their original licenses linked above.

About

Portable Claude Code workflow: rules, skills, hooks, agents — devcontainer + Codespaces ready

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages