Raftly documentation

Raftly is a Claude Code plugin that acts as a senior product and engineering organization around your repository. This page covers installing it, using it, and what it does.

Install

Option 1: plugin from the marketplace (recommended)

In Claude Code:

/plugin marketplace add roszhan2684/raftly
/plugin install raftly@raftly

Or from your terminal:

claude plugin marketplace add roszhan2684/raftly
claude plugin install raftly@raftly

Option 2: try it without installing

git clone https://github.com/roszhan2684/raftly.git
claude --plugin-dir ./raftly

Option 3: personal skill (no plugin)

git clone https://github.com/roszhan2684/raftly.git
mkdir -p ~/.claude/skills
cp -R raftly/skills/raftly ~/.claude/skills/raftly

Requirements: Claude Code and Python 3.9 or newer on your PATH. Raftly's scripts use only the Python standard library. There is no account, backend, API key or telemetry.

Use

Open Claude Code in any project folder and type a command. One installation works across all your repositories, and each project gets its own .raftly/ folder.

You type	Raftly does
`/raftly I want to build …`	Plans a new product: classify, research, product, design (2–3 directions), architecture, build graph, blueprint package.
`/raftly`	In a repo with `.raftly/`: resumes where you left off and does the next recommended action.
`/raftly build next`	Implements the next unblocked capability, runs your tests and records real evidence.
`/raftly review`	Reviews code or architecture against requirements and decisions, and detects drift.
`/raftly launch`	Runs the production gate and the "forgotten 20%" audit. Readiness comes from evidence only.
`/raftly doctor`	Diagnoses project health, and says "no change" when nothing material is wrong.
`/raftly explain why PostgreSQL?`	Answers from the recorded decisions and evidence.
`/raftly handoff` · `replay` · `postmortem`	Onboarding document · project history · incident record.

You can also just talk to it: "Use MongoDB instead of PostgreSQL" records a founder override, and "I hate rounded buttons" becomes a preference for this project only.

If another plugin also defines /raftly, use the fully qualified name /raftly:raftly.

How it works

Modes

Raftly infers what you need: greenfield (idea → blueprint), build, review, recovery (fix a half-built repo without rewriting it), migration (with rollback plans), scale, launch, operate (incidents, feedback), handoff and doctor.

Senior roles and decision authority

Every decision is routed to the senior-most relevant role: 22 roles, from Head of Product Strategy to Principal SRE. Decisions come in three levels:

Auto: routine, reversible choices. Made silently.
Recommend: important but reversible. Recorded as a decision record with reasoning and confidence, and work continues.
Founder: genuine business calls such as pricing or target customer. You're asked, batched into one round.

Evidence before "done"

Features move from planned to implemented, then verified, then complete. Raftly's scripts refuse to mark anything verified, complete or passing without a recorded test, review or measurement.

Proportionate production gate

45 launch checks and a 29-item "forgotten 20%" audit, each applied only when it fits your product's profile. A client-only calculator gets 16 applicable checks. A multi-tenant AI SaaS gets 42.

What it creates

File	Purpose
`.raftly/state.yaml`	Mode, stage, blueprint status, progress, readiness, history
`docs/PRODUCT.md`, `DESIGN.md`, `ARCHITECTURE.md`, `BUILD.md`, `EXECUTIVE.md`	The blueprint documents
`docs/DIAGRAMS.md`	Five Mermaid diagrams: system architecture, user flow, screen map, data model, critical-path sequence
`docs/decisions/`	Decision records (options, evidence, confidence, revisit triggers)
`docs/features/` and `docs/prompts/`	Feature specs and one implementation prompt per capability
`.raftly/build-graph.yaml`, `evidence.yaml`, `gate.yaml`	Dependency graph, evidence links and test results, production gate
`docs/blueprint.html`, `docs/deck.md`	Visual blueprint and slide deck, rendered from the project state

That's the layout for a new project: Raftly creates a folder named after the product if you start somewhere that isn't a project. In an existing repository, Raftly leaves your docs/ alone and keeps its documents in .raftly/, with the blueprint and deck in artifacts/. Commit both folders with your project. It's plain Markdown and YAML.

Update and uninstall

claude plugin update raftly@raftly
claude plugin uninstall raftly@raftly

Troubleshooting

/raftly doesn't appear: run /plugin to check it is installed and enabled, then restart Claude Code.
Python errors: make sure python3 --version prints 3.9 or newer.
Name clash: use /raftly:raftly.
Older projects with a .forge/ folder (the pre-release name): Raftly still reads them, and /raftly offers to migrate.

Source, examples and full reference: github.com/roszhan2684/raftly. Report bugs or ideas in GitHub issues.

Raftly provides engineering and product readiness guidance. It does not replace professional legal, compliance, security, accessibility or regulatory review.