Coding assistants
Factflow carries its own assistant harness in .claude/. It configures how a coding assistant works in this repo: which conventions load automatically, which domain knowledge is available on demand, and which multi-step workflows are one command away.
This is tooling around development. The development process it automates stands on its own — you can follow every step by hand.
What lives where
Section titled “What lives where”| Directory | Loads | Purpose |
|---|---|---|
rules/ | Automatically, by file path | Constraints. Editing a matching file pulls the rule into context |
skills/ | On demand | Domain workflows with worked examples and fixture patterns |
commands/ | When invoked as /name | Multi-step procedures — issue creation, PR review, releases |
agents/ | When delegated to | Subagent definitions with their own tool sets |
hooks/ | On tool events | Scripts that intercept actions |
issues/ | — | Live design docs and task files for in-flight work (tracked) |
history/ | — | Archived issue folders after their PR merged (tracked, read-only) |
.claude/session-state/ and .claude/worktrees/ are gitignored runtime state, not configuration.
Rules are scoped by path
Section titled “Rules are scoped by path”The thirteen files in rules/ each declare which paths they govern, so a rule only applies where it is relevant. Editing backend/packages/factflow-infra/src/.../queue/artemis/async_adapter.py pulls in the queue-provider and async-pattern rules; editing a React component pulls in the frontend conventions instead.
| Rule | Governs |
|---|---|
python-semantics.md | backend/**/*.py — typing, package boundaries |
async-patterns.md | Queue protocol, concurrency layering, completion detection |
adapter-conventions.md | backend/packages/workflows/** — the adapter contract |
queue-provider-conventions.md | backend/**/queue/** — Artemis, RabbitMQ, Pulsar specifics |
storage-conventions.md | backend/**/storage*.py — the sidecar pattern, replay constraints |
lineage-conventions.md | Correlation, pending children, failure isolation |
llm-conventions.md | LLM factory, rate limiting, error classification |
pipeline-yaml.md | backend/config/**/*.yaml — config validation |
testing-discipline.md | backend/**/tests/** — fixture selection, invariants |
api-contract.md | Cross-stack type files — response conventions, SSE |
frontend-conventions.md | frontend/src/** — React patterns, API layer |
go-conventions.md | cli/**/*.go — CLI patterns, output formatting |
thoroughness.md | Global — pattern completeness, destructive operations |
These are the authority. When a docs page and a rule disagree, the rule wins, and the code wins over both.
Skills carry domain knowledge
Section titled “Skills carry domain knowledge”Sixteen skills sit flat one directory deep, prefixed by scope: backend-* for backend domains (queue testing, pipeline testing, adapter patterns, application config, storage patterns, and the rest), shared-* for cross-cutting ones (shared-freestyle, shared-mermaid, shared-epistemic-evaluation, shared-slack-message), plus docsite for this documentation site.
A skill is loaded when the task matches it — writing queue tests pulls in backend-queue-testing, which knows the fixture chain and the provider-specific gotchas. Rules constrain; skills instruct.
Commands
Section titled “Commands”| Command | Argument | Run by | Does |
|---|---|---|---|
/ff-issue | free-form title | Anyone | Creates the issue, writes design.md, links it from the issue body |
/ff-start | <issue-number> | Author | Worktree, branch, task.md, implement, self-review, PR |
/ff-review | <PR-number> | Reviewer | Checks out the PR branch, reads changed files, runs the gates, submits a review |
/ff-address | <issue-or-PR-number> | Reviewer | Carries out the fixes the review called for, pushes, replies |
/ff-code-review | backend | frontend | cli | all | path | Anyone | Standalone quality audit. No GitHub interaction, no PR |
/ff-release | <semver> (optional) | Whoever cuts it | The release cycle — see Cutting a release |
/freestyle | free-form description | Anyone | Understand → isolate → fix → verify → pause |
/scribe | — | Anyone | Loads knowledge-pipeline context |
/ff-review and /ff-address belong to the reviewer on a peer-reviewed PR — the reviewer both finds the problems and fixes them, then approves so the author can merge. On a self-reviewed PR the author runs both. See Review and merge for which path applies when.
Two modes
Section titled “Two modes”/ff-start is the ceremonial path. It produces the full artifact trail — issue, design doc, task file, PR, archive — and is what you want for anything a reviewer will need context on. It isolates work in a git worktree so the main tree stays clean.
/freestyle is the direct path for a bug you already understand. It still branches and runs the same gates, but produces no issue artifacts and stops after verifying rather than opening a PR. It hands off to the ceremonial commands when a fix turns out bigger than it looked: "create an issue for this" → /ff-issue, "let's do this properly" → /ff-start.
Both stop and wait rather than committing on their own. Neither pushes without being asked.
Working effectively
Section titled “Working effectively”- Source is the only authority. Not a docs page, not a comment, not this page. Verify field names, flags and response shapes against the code that runs.
- State the scope. "Fix the CLI replay command" gets a better result than "fix replay", because it tells the assistant which stack owns the problem and which types must follow.
- Cross-stack changes propagate. A backend response-shape change obliges
frontend/src/types/andcli/internal/api/types.goin the same PR. Theapilabel exists to mark exactly this. - Untracked files are never deleted.
backend/output/,data/andstorage/hold confidential pipeline data that is gitignored by design and not reproducible. A hook enforces this.