Show HN: AI-factory – a spec-driven pipeline that stops AI agents rotting code

0→1 with an AI coding agent is easy. 1→100 is where it gets hard — the code that survives review, scales past the demo, and doesn't quietly rot the codebase over months. That's where ai-factory comes in.

A complete spec-driven development practice for AI coding agents — skills, agents, deterministic hooks, and a role-based capability model — installed once and parameterized to your org through config, not forks.

git clone https://github.com/highflame-ai/ai-factory.git cd ai-factory && ./install.sh install.sh is idempotent and repair-capable. It symlinks:

It also writes the aif CLI shim to ~/bin ( doctor , check , agents render , compile , renumber ), scaffolds ~/.claude/aif/config.yml (delegation off by default), and finishes with aif doctor — a full environment health check that prints a copy-pasteable fix for every failure. ./install.sh --dry-run previews; --repair re-stamps after moving the clone.

The journey: install → fill in workspace-CLAUDE.md and the machine config ( ~/.claude/aif/config.yml ) → run claude → /init in each code repo to bootstrap its .aif/ structure → then fill that repo's .aif/config.yml (optionally starting from a skills/presets/ starter). Along the way, an adopting org customizes five things (details in examples/README.md ):

AIF pipeline (spec-driven lifecycle) Skill Description /init Bootstrap .aif/ structure in a repo /onboard Adopt the toolkit in an existing codebase — drafts the service map, starter experts, conventions, and config for review /measure Measure whether the toolkit is paying off — delivery/quality metrics from git, PRs, and .aif/ artifacts, with honest caveats /spec Write requirement specs from feature requests /architect Design architecture and break requirements into tasks /validate Validate any AIF phase output before advancing /proceed End-to-end pipeline: validate → architect → implement → reflect → review → PR → wrapup /sprint Parallel pipeline orchestrator — multiple /proceed runs across REQs ( --workflow engine) /reflect Post-implementation self-review before formal review /review Multi-agent code review (correctness, quality, architecture, tests, security) /adversary Adversarial review of any artifact — assumes it is wrong and tries to prove it /canary Canary deployment with smoke tests /wrapup Close out a feature — commit, merge, deploy, update artifacts /bugfix Streamlined bug fix workflow /status / /manifest Local / remote-derived view of in-flight AIF work /analyze Codebase health audit /optimize API cost & performance scanner /template-drift Detect drift between a project's .aif/templates/ and the toolkit's Core workflow:

/spec → /validate → /architect → /validate → implement → /reflect → /review → merge → /wrapup Org workflow Skill Description /using-aif Meta-skill routing table — injected at SessionStart /from-issue Issue → merge-ready PR orchestrator (classify, route, implement, ship, babysit CI) /feature-prep Does the spec registry need an entry first? Where do tests go? /grill-feature Adversarial design review before architectural work /ship Pre-merge orchestrator — parallel reviewer fan-out → go/no-go → post-deploy verify /triage-dev Investigate your shared dev environment in a configured observability order /source-driven Read the authoritative source (config, code, MCP) instead of guessing /incremental-implementation Thin vertical slices, one repo at a time /debug Local repro and root-cause; Phase 1 = fast deterministic feedback loop /deprecate Multi-stage removal across your configured repos /git-workflow Commit prefixes (configurable regex), atomic commits, branching, worktrees, PR flow /handoff Compact a multi-repo session into a handoff doc /release-notes Multi-audience release-notes draft (customer, engineering, executive) from a git tag or range /dep-update Vetted dependency updates — changelog risk review, isolated branch, test-proven, one PR per batch /license-audit SBOM + license compliance — resolve every component's license, judge against org.license_policy /rotate-secrets Proactive secret rotation — expiry gate over the secrets: inventory, overlap-pattern rotation, human gate before revoke /audit-permissions Review and prune risky standing Claude permission grants in .claude/settings*.json (pairs with aif doctor 's permissions-audit ) /doc-drift Find and fix docs made stale by a change — diff-derived surfaces, stale vs missing classification /threat-model STRIDE threat model from a spec/RFC — assets, trust boundaries, refuted threats, mitigation punch list /expert Curate a domain expert — path-scoped context distilled from your docs, injected only when a change touches its domain /add-detector Template: scaffold a module in an extensible service, following your documented pattern /new-admin-module Template: scaffold a CRUD module (schema → migration → repository → service → handler → registration) Agents 26 subagents in agents/ , each with tier-based model selection rendered by aif agents render (config: ~/.claude/aif/config.yml ).

/expert curates a domain expert : dense context distilled from your own docs and code, stored at .aif/experts/<name>.md , and injected into a task only when the change touches that domain (matched by the expert's applies_to globs). Context engineering — React context on a React change, DynamoDB context on a data-access change, neither on unrelated work. /review activates matching experts automatically. workspace-CLAUDE.md holds facts true everywhere, references/ are cross-cutting checklists, lessons are relevance-ranked incidents, experts are path-scoped domain knowledge. The applies_to globs are also the future compile key for path-scoped rules in other assistants (Copilot applyTo , Cursor globs) — that emission is the next phase.

roles/*.yaml is the single source of truth for what each agent role may do. A reviewer declares {envelope: [read, grep, glob, bash], write: false} once, and aif compile emits it as:

Exceptions are declared in the role file with a reason, never quietly in an agent's own frontmatter. aif compile --check is the drift gate. This is what makes the toolkit's practice portable across agent runtimes rather than Claude-only.

Deterministic gates in hooks/ , wired through each repo's .claude/settings.json . All wrapped in if [ -x … ] so machines without the install no-op silently.

skills/templates/settings.example.json is the shared per-repo .claude/settings.json (permissions + hooks). Maintainers roll it out across a workspace with:

tools/fleet/distribute-settings.sh -n # dry-run: every git repo in the workspace AIF_REPO_GLOB= ' acme-* ' tools/fleet/distribute-settings.sh # narrow to a repo glob tools/fleet/open-settings-prs.sh # open a PR per modified repo Both scripts resolve the workspace root the same way as install.sh : AIF_WORKSPACE env → machine config workspace.root → the clone's parent directory.

/init copies the richer skills/templates/claude-settings-template.json (same hooks, plus the AIF pipeline allow/ask lists) into projects it bootstraps.

.aif/ ETHOS.md # copy of the toolkit's ETHOS.md (keeps skills working inside git worktrees) context/ # project overview, architecture, conventions, taxonomy (retrieval tags) specs/ # requirement docs, architecture docs, tasks bugs/ # bug reports knowledge/ # assumptions/ (validated) and lessons/ (learned) templates/ # copies of artifact templates (from this toolkit) partials/ # copies of shared shell snippets (from this toolkit) workflows/ # copies of Dynamic Workflow scripts (from this toolkit) config.yml # only if you opt into cross-repo coordination (or copy in a preset) The toolkit repo contains the process ; each code repo contains the artifacts . Skills read .aif/config.yml at runtime for anything project- or org-specific — /init creates it only when you opt into cross-repo coordination (otherwise copy it from a preset or the template). Cross-repo features (spanning api + web + worker) are supported via the repos: block.

AGENTS.md — the agent-facing guide to this repo (layout, install, house rules) — readable by any AGENTS.md-aware tool; CLAUDE.md imports it skills/ETHOS.md — the principles injected into every AIF skill examples/ — how an org extends the toolkit (skill/agent skeletons, house rules) references/ — on-demand checklists; several are fill-in templates workspace-CLAUDE.md — always-loaded workspace context, as a fill-in template tips.md — Claude Code power-user guide skills/partials/ — shared POSIX shell functions (forge PR adapter for GitHub/Azure DevOps, id allocation, telemetry) skills/workflows/ — deterministic Dynamic-Workflow scripts for /sprint --workflow tools/ — the aif CLI, the skill linter, and the opt-in delegation CLIs skills/presets/ — stack-shaped starter configs for .aif/config.yml ./catalog.sh — terminal inventory of every skill, agent, hook, and reference Updating cd " $( readlink ~ /.claude/skills ) " && git pull git pull applies once the toolkit is a published git repo with a remote (or your fork of it). Since ~/.claude/skills is a symlink, changes are picked up immediately by every session.

New skills follow the toolkit conventions ( .aif/context/conventions.md ): POSIX-only shell in fences, two-level .aif/ → ~/.claude/skills/ fallback for every asset, PR operations through the forge adapter, org values through config (never hardcoded), python3 tools/lint-skills/check.py clean. New agents get tier: frontmatter, an entry in tools/aif/agents_render.py , and an aif agents render run.