Lewati ke konten
TakoAPI
Kembali ke skill

fabricator

oleh artemiv4nov

Windsurf
โ€”Belum ada penilaian
Penilaian Anda

Ringkasan

Fabricator: choose the right artifacts, ground in repo truth, verify with evidence. For Windsurf Cascade.

Deskripsi

# Fabricator

**A programmable kernel that enforces a software development lifecycle on AI coding agents.**

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![Status](https://img.shields.io/badge/status-experimental-orange.svg)](#project-status)

Instructions are suggestions. Code is enforcement.

Fabricator sits between your IDE and a coding agent, intercepting every tool call through IDE
hooks. Instead of asking an agent to follow a process written in Markdown, it runs the process
as a state machine in Python: the agent cannot write code until it has written a plan, and
cannot finish until independent review agents have checked the work.

Works with **Windsurf Cascade**, **Claude Code** and **GitHub Copilot CLI** from one install.

---

## Why

Agents skip steps. Told to "plan first, then implement," they write a plan and start editing in
the same turn. Told "don't touch config," they touch config. Prompt-level rules are advisory,
and an agent under context pressure drops them first.

Fabricator moves the rules out of the prompt and into a kernel the agent cannot talk its way
past. Each lifecycle state declares which capabilities are available. A write to `plan.md` that
does not match the required structure is rejected before it lands, with the specific list of
what is missing.

---

## Quick start

Requires Python 3.9+ and one of: Windsurf, Claude Code, or GitHub Copilot CLI.

```bash
git clone https://github.com/artemiv4nov/fabricator.git
cd fabricator
python3 configure.py /path/to/your/project
```

That installs the kernel into `/path/to/your/project/.fabricator/`, creates a virtualenv, and
writes hook configuration for every supported IDE it detects.

Then, in your agent's chat:

```
session:name fix-yaml-parser
Handle anchors and aliases in the YAML parser.
```

The kernel creates `.fabricator/001-fix-yaml-parser/`, enters the `inited` state, and answers
with steering:

```json
{
  "state": "inited",
  "direction": "Study the repository and build a grounded understanding of the codebase.",
  "goal": "Write context-map.md into the session work_path.",
  "artifacts": ["context-map.md"],
  "allowed": ["read_code", "run_command", "mcp_tool_use", "write_session", "write_context_map"]
}
```

Follow the steering. Every state tells you what to produce next, and refuses everything else.

---

## How it works

### The lifecycle

Eight states, from task inception to verified completion:

```
                          session:rethink
              โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
              โ”‚                                                     โ”‚
              โ–ผ                                                     โ”‚
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ inited  โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚  draft  โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ blocked_on_human โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ grounded โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
 context-map.md  task.md valid   session:approve_task     plan.md + review
                                 session:rethink โ—€โ”€โ”€โ”€โ”€โ”        โ”‚
                                                      โ”‚        โ”‚
              โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜        โ”‚
              โ”‚                                                 โ”‚
              โ”‚   session:replan          plan approved          โ”‚
              โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
              โ”‚  โ”‚
              โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
              โ”‚  โ”‚  โ”‚                          โ”‚
              โ–ผ  โ–ผ  โ–ผ                          โ”‚ verification failed
          โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”     โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
          โ”‚ active โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ verifying โ”‚โ”€โ”€โ”€โ”€โ–ถโ”‚ completed โ”‚
          โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
           result.md      3 agents check    session:rework โ”€โ”€โ–ถ active
                          pass/fail         session:replan โ”€โ”€โ–ถ grounded
                                            session:rethink โ”€โ–ถ draft
```

| State | Agent produces | Kernel blocks | Advances when |
|---|---|---|---|
| `inited` | `context-map.md` โ€” facts only, no opinions | every write except the context map | the context map is written |
| `draft` | `task.md` from template | code writes | `task.md` passes section validation |
| `blocked_on_human` | โ€” | all writes | you run `session:approve_task` |
| `grounded` | `plan.md` with Input/Output/Depends-on steps | code writes | review agents approve the plan |
| `active` | code, then `result.md` | writes to kernel-owned paths | `result.md` passes manifest validation |
| `verifying` | โ€” | everything | all review agents pass |
| `completed` | minor edits | structural changes | โ€” |

### Artifact validation is the gate

Transitions are not triggered by the agent announcing it is done. They are triggered by an
artifact passing validation at write time:

- **`task.md`** must contain every section from the template. Missing sections โ†’ write blocked,
  with the list.
- **`plan.md`** must follow the step structure. Malformed steps โ†’ write blocked.
- **`result.md`** must carry the full release manifest, explicit acceptance-criteria coverage,
  and a valid final status.

This is what prevents the common failure where a file gets written but the process silently does
not advance.

### Capability gating

Every intercepted action is classified, then checked against the current state:

| Capability | Allowed in |
|---|---|
| `read_code` | all states โ€” reading is never blocked |
| `write_context_map` | `inited` |
| `write_task` | `draft`, `blocked_on_human` |
| `write_plan` | `grounded` |
| `write_result` | `active` |
| `write_any` | `active` |
| `run_command` | all states |
| `mcp_tool_use` | all states |

---

## Safety model

Read this before installing. Fabricator makes some real guarantees and some deliberately weaker
ones, and the difference matters.

### What is actually enforced

**Capability gating and artifact validation.** These run in the kernel, on every hook event,
before the tool executes. An agent cannot write `plan.md` in the `active` state, and cannot write
a malformed one in `grounded`. Paths owned by the kernel are resolved and compared against
protected roots, so `../` traversal does not escape them.

### What is a guardrail, not a boundary

**Shell command filtering.** Commands targeting `.fabricator/`, `.windsurf/`, `.claude/` or
`.kernel/` with a write are blocked by matching the command string against a list of write
tokens. This stops an agent from casually overwriting kernel state. It does **not** stop a
determined or prompt-injected one โ€” string matching on shell commands is bypassable, and the
token list is not exhaustive. Treat it as protection against accidents, not against attacks.

### Review agents run unsandboxed, by design

The kernel spawns review and verification agents as child processes with their safety controls
switched off:

```json
"codex":   ["--skip-git-repo-check", "--dangerously-bypass-approvals-and-sandbox"]
"claude":  ["--dangerously-skip-permissions", "--settings", "{\"disableAllHooks\": true}"]
"copilot": ["--allow-all", "-s"]
```

This is intentional. Review agents need to run builds, tests and linters unattended โ€” a tester
that stops to ask permission for `./gradlew test` is useless. Their role is to read and check,
not to change code.

What it costs you: these child agents inherit the parent environment, including any credentials
in it, and because of `disableAllHooks` they run **outside** Fabricator's own enforcement. If you
are not comfortable with that, edit `agents.json` and remove the flags before installing โ€” the
runners read every flag from that file and have no built-in defaults.

### Credentials

Skill scripts read credentials from `.fabricator/credentials.ini` or from environment variables.
`.fabricator/` is gitignored by the installer. Generate a template with:

```bash
python3 configure.py --setup-credentials /path/to/your/project
```

---

## How it compares

Hook-enforced agent workflows are a crowded field. An honest placement:

| Project | Enforcement | Scope |
|---|---|---|
| [cc-sessions](https://github.com/GWUDCAP/cc-sessions) | blocks edit tools until you approve a plan | Claude Code |
| [statewright](https://github.com/statewright/statewright) | state machine with per-state tool allow-lists | Claude Code, Codex, Cursor, OpenCode |
| [governed-workflow](https://github.com/IgnatRozhkoTR/governed-workflow) | phase gates, scope locks, approval panel | Claude Code |
| **Fabricator** | full SDLC state machine with artifact validation and spawned review agents | Windsurf, Claude Code, Copilot |

Fabricator's distinguishing choices are that transitions are driven by **validated artifact
content** rather than by the agent or the user declaring a phase complete, and that one kernel
serves several IDEs through an adapter layer. If you only use Claude Code and want something
smaller and more mature, the projects above are good.

---

## Skills

Reusable, domain-specific procedures. Each is a directory with `SKILL.md` and helper scripts.

| Skill | Use when |
|---|---|
| `tool-spec` | the task needs architectural design before implementation |
| `tool-model` | the solution has complex stateful logic or async flows |
| `tool-contract` | the work touches API, schema, deeplink or storage boundaries |
| `tool-implement` | the task definition is ready and code must be written |
| `tool-verify-plan` | verification commands are unclear or undocumented |
| `tool-verify-run` | changes need build, test and lint verification |
| `tool-git` | changes are ready to commit |
| `tool-bitbucket` | a pull request must be created or reviewed |
| `tool-jira` | the task requires reading or updating Jira issues |
| `tool-slack` | the task requires Slack messages or files |
| `tool-allure` | test-case data is needed from Allure TestOps |
| `tool-publish-spec` | a stable spec should become a canonical reference |

Read any skill's contract with `cat skills/tool-<name>/SKILL.md`.

---

## Command reference

All interaction happens through `session:<command>` on its own line in the chat.

**Sessions**

| Command | Purpose |
|---|---|
| `session:name <slug>` | create or resume a session |
| `session:skip` | allow writes in an unnamed, unenforced session |

**Transitions**

| Command | From | To |
|---|---|---|
| `session:approve_task` | `blocked_on_human` | `grounded` |
| `session:rework` | `completed`, `verifying`, `active` | `active` |
| `session:replan` | `completed`, `active`, `grounded` | `grounded` |
| `session:rethink` | `completed`, `active`, `grounded`, `blocked_on_human` | `draft` |

**Settings**

| Command | Purpose |
|---|---|
| `session:set <key> <value>` | change a kernel setting |
| `session:unset <key>` | reset a setting to its default |

| Key | Default | Effect |
|---|---|---|
| `work_verification` | `true` | when `false`, `result.md` skips the verification agents |

---

## Configuration

The installer writes hook configuration per IDE. The source templates live at the repository
root:

| File | Target |
|---|---|
| `windsurf_hooks.json` | Windsurf Cascade |
| `claude_hooks.json` | Claude Code |
| `copilot_hooks.json` | GitHub Copilot CLI |

Hooks invoke `fabricator_runtime.py` with `${VENV_PYTHON}` and `${REPO_ROOT}` substituted at
install time โ€” no absolute paths are baked in. `agents.json` defines which CLI backs each review
agent; `agent_roles.json` defines what each role checks.

The kernel finds the repository root by walking up for `AGENTS.md` or `.windsurf/`. Override with
`--repo-root`.

---

## Development

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python3 -m pytest tests/ -q
```

Project layout:

| Path | Contents |
|---|---|
| `fabricator_kernel/` | the kernel: FSM, hooks, enforcement, agents, storage |
| `skills/` | reusable procedures |
| `rules/` | behavioural rules loaded into the agent |
| `templates/` | `task.md`, `plan.md`, `result.md` templates |
| `tests/` | unit, integration and end-to-end suites |
| `configure.py` | installer |

---

## Troubleshooting

**`task.md` write is blocked with "missing sections".** The template is authoritative. Compare
against `templates/task.md` and add every heading it lists.

**`plan.md` written but the plan review returns blockers.** Read the `blockers` list in the
response, address each one, rewrite the file. The review agents re-run on every write.

**Hooks do not fire.** Confirm the IDE picked up the generated config, and that
`.fabricator/.venv/` exists in the target project. Re-run `configure.py` to repair.

**An agent is stuck asking for permission.** It is probably in a state that does not grant the
capability it wants. The steering response lists `allowed` โ€” read it.

---

## Project status

Experimental, and built primarily for its author's own work. The kernel and lifecycle are stable
enough for daily use; the shell-command filter and the review-agent sandboxing are the weakest
parts and are documented as such above. Issues and pull requests are welcome.

---

## License

[Apache License 2.0](LICENSE).

Instalasi

Pasang skill dari https://github.com/artemiv4nov/fabricator

Skill ini belum dipublikasikan di registri ClawHub. Tempel prompt ke coding agent Anda โ€” Claude Code, Cursor, Codex โ€” dan skill-nya akan dipasang langsung dari repositori sumbernya.

Buka repositori

Tautan