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.

Why ai-factory

Faster— across our own development at Highflame, the spec-driven pipeline plus parallel sprint orchestration routinely delivers3–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 reachmain

.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/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:codeoidcodeoid 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 theaif

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 declarativepacks/

codeoidpacks (schema: codeoid/pack@v1

). A pack is data-only (apack.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/ starter). Along the way, an adopting org customizes five things (details in

):

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 theskills/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

(orAIF_COMMIT_PREFIX_REGEX

) to mirror your CI's commit gate; add your org's key prefixes tohooks/secret-scan.sh

.Your own skills and agents— skeletons and house rules inexamples/

.

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/, 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, adversaryScanners/explorers: api-cost-scanner, db-perf-scanner, latency-scanner, architecture-mapper, convention-auditor, feature-tracer, integration-explorer, delegate-pre-passPipeline: 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 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:Claude— validation ofagents/*.md

tools:

frontmatter (the native layer;--check

fails on any agent exceeding its role's envelope), plusper-role settings overlays for headless/CI sessionscompiled/claude/

Codex—sandbox profiles per rolecompiled/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 gatewaycompiled/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/, 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 (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 skillskills/ETHOS.md

— how an org extends the toolkit (skill/agent skeletons, house rules)examples/

— on-demand checklists; several are fill-in templatesreferences/

— always-loaded workspace context, as a fill-in templateworkspace-CLAUDE.md

— Claude Code power-user guidetips.md

— shared POSIX shell functions (forge PR adapter for GitHub/Azure DevOps, id allocation, telemetry)skills/partials/

— deterministic Dynamic-Workflow scripts forskills/workflows/

/sprint --workflow

— thetools/

aif

CLI, the skill linter, and the opt-in delegation CLIs— stack-shaped starter configs forskills/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.

source & further reading

github.com — original article