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

Highflame released ai-factory, an open-source spec-driven development pipeline for AI coding agents that enforces deterministic gates and multi-agent review to prevent codebase degradation. The pipeline, which the company says delivers 3-5x faster feature delivery in internal use, installs as slash commands for Claude Code or as a declarative pack for Highflame's codeoid runtime.

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. Why ai-factory Faster — across our own development at Highflame, the spec-driven pipeline plus parallel sprint orchestration routinely delivers 3–5x : features/PRs shipped, bugs resolved, and time-to-merge, vs. ad-hoc AI-assisted coding. our internal experience — your mileage will vary Less slop — deterministic gates, an adversarial multi-agent review bench, and a verification-is-non-negotiable ethos: unreviewed AI output can't reach main . Leaner context — heavy research and review run in subagents with their own context windows; the main session stays focused. Two ways to run it: Standalone in — 41 skills as slash commands Claude Code https://claude.com/claude-code /spec → /architect → /proceed → /ship , symlinked live into every session. Clone, ./install.sh , go. Under — the same methodology as a declarative pack on codeoid's multi-session runtime, with per-agent identity and cross-session memory: codeoid https://github.com/highflame-ai/codeoid codeoid run --pack aif-sdlc . Three layers: The AIF pipeline — a spec-driven development lifecycle spec → architect → validate → implement → reflect → review → ship with parallel sprint orchestration, a multi-agent review bench, and the aif health CLI. The org-workflow layer — day-to-day engineering skills issue-to-PR orchestration, debugging, deprecation, git conventions, session handoffs, environment triage , review agents, and deterministic hooks. Everything org-specific resolves through .aif/config.yml — nothing is hardcoded, and every skill states what it does when a config key is absent. The pack registry — the methodology as declarative packs/ codeoid https://github.com/highflame-ai/codeoid packs schema: codeoid/pack@v1 . A pack is data-only a pack.yaml + capability roles + constitution ; codeoid runs its governed phase pipeline. Contribute a pack once, and any team can select it. See— first pack: packs/README.md . aif-sdlc git clone https://github.com/highflame-ai/ai-factory.git cd ai-factory && ./install.sh install.sh is idempotent and repair-capable. It symlinks: | Link | Target | Consumed by | |---|---|---| ~/.claude/skills | skills/ | every skill /spec , /ship , … | ~/.claude/agents | agents/ | every subagent @security-reviewer , … | ~/.claude/aif-hooks | hooks/ | the hooks block in each repo's .claude/settings.json | ~/.claude/aif-bin | bin/ | sidecar helpers | ~/.claude/aif-references | references/ | on-demand checklists | <workspace /CLAUDE.md | workspace-CLAUDE.md | always-loaded workspace context fill-in template . Workspace root: AIF WORKSPACE env → ~/.claude/aif/config.yml workspace.root → the clone's parent dir | 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/ /highflame-ai/ai-factory/blob/main/skills/presets starter . Along the way, an adopting org customizes five things details in : /highflame-ai/ai-factory/blob/main/examples/README.md examples/README.md per repo — scaffolded by .aif/config.yml /init from when you opt into cross-repo coordination, or copied in afterward from a preset — stack, sibling repos, and the skills/templates/config-template.yml org: / environments: / mcp: / local stack: / regression: / tenancy: sections that drive the org-workflow skills.— the always-loaded platform-context template service map, auth contract, conventions . workspace-CLAUDE.md Fill-in references — MCP cheatsheet, regression markers, known-warts registry, tenancy/JWT checklists. Hook configuration — org.commit prefix regex or AIF COMMIT PREFIX REGEX to mirror your CI's commit gate; add your org's key prefixes to hooks/secret-scan.sh . Your own skills and agents — skeletons and house rules in examples/ . | 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 | 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 | 26 subagents in agents/ /highflame-ai/ai-factory/blob/main/agents , each with tier-based model selection rendered by aif agents render config: ~/.claude/aif/config.yml . Review bench : correctness-reviewer, security-auditor, architecture-reviewer, quality-reviewer, code-quality-auditor, test-auditor, reflector, adversary Scanners/explorers : api-cost-scanner, db-perf-scanner, latency-scanner, architecture-mapper, convention-auditor, feature-tracer, integration-explorer, delegate-pre-pass Pipeline : task-implementer, pipeline-runner Org workflow : security-reviewer invariant-driven audit , cross-repo-impact, migration-analyzer, pr-shepherd, gemini-reviewer, cedar-policy-reviewer if you use Cedar , local-stack-runner, kind-regression-runner /expert /highflame-ai/ai-factory/blob/main/skills/expert/SKILL.md 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 /highflame-ai/ai-factory/blob/main/roles 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: Claude — validation of agents/ .md tools: frontmatter the native layer; --check fails on any agent exceeding its role's envelope , plusper-role settings overlays for headless/CI sessions compiled/claude/ Codex —sandbox profiles per role compiled/codex/config.toml Copilot —paste-in role boundaries convention — Copilot has no enforcement surface compiled/copilot/ Cedar —schema + policies, for orgs enforcing agent capabilities at a gateway compiled/cedar/ 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/ /highflame-ai/ai-factory/blob/main/hooks , wired through each repo's .claude/settings.json . All wrapped in if -x … so machines without the install no-op silently.| Hook | Event | Does | |---|---|---| session-start-skills.sh | SessionStart | Injects the /using-aif routing table | go-format.sh , ts-format.sh , py-format.sh , rust-format.sh | PostToolUse Edit|Write | gofmt/goimports, prettier, ruff, rustfmt | secret-scan.sh | PreToolUse Bash | Blocks secret exposure and destructive commands | commit-prefix-check.sh | PreToolUse Bash | Enforces your CI's commit-subject regex AIF COMMIT PREFIX REGEX → org.commit prefix regex → Conventional Commits | precommit-gate.sh | PreToolUse Bash | Static analysis on staged files at git commit time | session-reflect.sh | Stop | One reflection turn → appends warts to the known-warts inbox | 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 /highflame-ai/ai-factory/blob/main/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. — the agent-facing guide to this repo layout, install, house rules — readable by any AGENTS.md-aware tool; AGENTS.md CLAUDE.md imports it— the principles injected into every AIF skill skills/ETHOS.md — how an org extends the toolkit skill/agent skeletons, house rules examples/ — on-demand checklists; several are fill-in templates references/ — always-loaded workspace context, as a fill-in template workspace-CLAUDE.md — Claude Code power-user guide tips.md — shared POSIX shell functions forge PR adapter for GitHub/Azure DevOps, id allocation, telemetry skills/partials/ — deterministic Dynamic-Workflow scripts for skills/workflows/ /sprint --workflow — the tools/ aif CLI, the skill linter, and the opt-in delegation CLIs— stack-shaped starter configs for skills/presets/ .aif/config.yml ./catalog.sh — terminal inventory of every skill, agent, hook, and reference 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. MIT — see LICENSE /highflame-ai/ai-factory/blob/main/LICENSE .