ksforge

ksforge turns change requests into controlled Claude Code workflows.

export ANTHROPIC_API_KEY=...

ksforge implement --change "As a user, I want to reset my password via email."

ksforge is a small orchestration layer, written in Rust, that:

1. takes a change request,
2. builds a controlled request (capability + constraints + validation policy) around it,
3. spawns Claude Code — the actual coding/agent execution engine — to explore and edit your workspace,
4. validates the result with commands you control,
5. and reports what changed, durably and resumably enough that a paused "I need a human decision" doesn't mean a hung CI job.

ksforge      = orchestration: change request, capability, policy, workflow, PR.
Claude Code  = execution engine: repository exploration, editing, reasoning.
GitHub Actions = automation runtime ksforge targets.
av           = a separate Kosmos artifact-transformation/variation layer,
               independent of this first version.

Quickstart

ksforge implement --change "As a user, I want to reset my password via email." --dry-run
ksforge implement --change "As a user, I want to reset my password via email."
ksforge review .
ksforge explain src/auth.rs
ksforge status <execution-id>
ksforge resume <execution-id> --decision <option-id>

See docs/02-quickstart.md.

GitHub Actions

- uses: chevp/ksforge@v1
  with:
    change-request: ${{ inputs.change-request }}
    capability: implement
    create-pull-request: "true"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Ready-to-copy template: examples/github-workflows/change-request-to-ksforge.yml. See docs/07-github-actions.md, including the resumable two-run pattern for when Claude Code needs a decision mid-run.

Documentation

01 — Installation	Binary release, build from source, Claude Code prerequisite
02 — Quickstart	First run, dry-run, the paused/resume flow
03 — Architecture	Layering, the Claude Code subprocess contract, what's verified vs. inferred
04 — CLI reference	Every command, flag, exit code, JSON shape
05 — Capabilities	implement / review / fix / explain, and how to add one
06 — Human-in-the-loop	The Execution state machine, pause/resume, what does and doesn't survive across CI jobs
07 — GitHub Actions	action.yml, workflow_dispatch examples, permissions, PR mode
08 — Validation	--validate, and why it's never model-controlled
09 — Security	Prompt injection posture, least privilege, secret handling
10 — Configuration	Environment variables and why there's no config file (yet)
11 — Integrations	Optional MCP servers via --mcp-config, and how that differs from a capability
12 — Interactive chat	ksforge chat / bare ksforge — conversational front end, local branch/commit/merge (confirmed)
13 — The model is outside the orchestration	Why the phase loop, tool grants, and "is it done" all live in Rust, not the prompt

Also: INSTALL.md (install/global setup), START.md (first run), BUILD.md (build/test/lint loop), CONTRIBUTING.md, SECURITY.md.

License

Apache-2.0