{"slug": "show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code", "title": "Show HN: AI-factory – a spec-driven pipeline that stops AI agents rotting code", "summary": "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.", "body_md": "**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.\n\nA 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.\n\n**Why ai-factory**\n\n**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`\n\n.**Leaner context**— heavy research and review run in subagents with their own context windows; the main session stays focused.\n\n**Two ways to run it:**\n\n**Standalone in**— 41 skills as slash commands ([Claude Code](https://claude.com/claude-code)`/spec → /architect → /proceed → /ship`\n\n), symlinked live into every session. Clone,`./install.sh`\n\n, 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`\n\n.\n\nThree layers:\n\n**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`\n\nhealth 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`\n\n— nothing is hardcoded, and every skill states what it does when a config key is absent.**The pack registry**() — the methodology as declarative`packs/`\n\n[codeoid](https://github.com/highflame-ai/codeoid)packs (`schema: codeoid/pack@v1`\n\n). A pack is data-only (a`pack.yaml`\n\n+ 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`\n\n.`aif-sdlc`\n\n```\ngit clone https://github.com/highflame-ai/ai-factory.git\ncd ai-factory && ./install.sh\n```\n\n`install.sh`\n\nis idempotent and repair-capable. It symlinks:\n\n| Link | Target | Consumed by |\n|---|---|---|\n`~/.claude/skills` |\n`skills/` |\nevery skill (`/spec` , `/ship` , …) |\n`~/.claude/agents` |\n`agents/` |\nevery subagent (`@security-reviewer` , …) |\n`~/.claude/aif-hooks` |\n`hooks/` |\nthe hooks block in each repo's `.claude/settings.json` |\n`~/.claude/aif-bin` |\n`bin/` |\nsidecar helpers |\n`~/.claude/aif-references` |\n`references/` |\non-demand checklists |\n`<workspace>/CLAUDE.md` |\n`workspace-CLAUDE.md` |\nalways-loaded workspace context (fill-in template). Workspace root: `AIF_WORKSPACE` env → `~/.claude/aif/config.yml` `workspace.root` → the clone's parent dir |\n\nIt also writes the `aif`\n\nCLI shim to `~/bin`\n\n(`doctor`\n\n, `check`\n\n, `agents render`\n\n, `compile`\n\n, `renumber`\n\n), scaffolds `~/.claude/aif/config.yml`\n\n(delegation **off** by default), and finishes with `aif doctor`\n\n— a full environment health check that prints a copy-pasteable fix for every failure. `./install.sh --dry-run`\n\npreviews; `--repair`\n\nre-stamps after moving the clone.\n\nThe journey: install → fill in `workspace-CLAUDE.md`\n\nand the machine config (`~/.claude/aif/config.yml`\n\n) → run `claude`\n\n→ `/init`\n\nin each code repo to bootstrap its `.aif/`\n\nstructure → then fill that repo's `.aif/config.yml`\n\n(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\n\n[):](/highflame-ai/ai-factory/blob/main/examples/README.md)\n\n`examples/README.md`\n\nper repo — scaffolded by`.aif/config.yml`\n\n`/init`\n\n(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`\n\n`org:`\n\n/`environments:`\n\n/`mcp:`\n\n/`local_stack:`\n\n/`regression:`\n\n/`tenancy:`\n\nsections that drive the org-workflow skills.— the always-loaded platform-context template (service map, auth contract, conventions).`workspace-CLAUDE.md`\n\n**Fill-in references**— MCP cheatsheet, regression markers, known-warts registry, tenancy/JWT checklists.** Hook configuration**—`org.commit_prefix_regex`\n\n(or`AIF_COMMIT_PREFIX_REGEX`\n\n) to mirror your CI's commit gate; add your org's key prefixes to`hooks/secret-scan.sh`\n\n.**Your own skills and agents**— skeletons and house rules in`examples/`\n\n.\n\n| Skill | Description |\n|---|---|\n`/init` |\nBootstrap `.aif/` structure in a repo |\n`/onboard` |\nAdopt the toolkit in an existing codebase — drafts the service map, starter experts, conventions, and config for review |\n`/measure` |\nMeasure whether the toolkit is paying off — delivery/quality metrics from git, PRs, and `.aif/` artifacts, with honest caveats |\n`/spec` |\nWrite requirement specs from feature requests |\n`/architect` |\nDesign architecture and break requirements into tasks |\n`/validate` |\nValidate any AIF phase output before advancing |\n`/proceed` |\nEnd-to-end pipeline: validate → architect → implement → reflect → review → PR → wrapup |\n`/sprint` |\nParallel pipeline orchestrator — multiple `/proceed` runs across REQs (`--workflow` engine) |\n`/reflect` |\nPost-implementation self-review before formal review |\n`/review` |\nMulti-agent code review (correctness, quality, architecture, tests, security) |\n`/adversary` |\nAdversarial review of any artifact — assumes it is wrong and tries to prove it |\n`/canary` |\nCanary deployment with smoke tests |\n`/wrapup` |\nClose out a feature — commit, merge, deploy, update artifacts |\n`/bugfix` |\nStreamlined bug fix workflow |\n`/status` / `/manifest` |\nLocal / remote-derived view of in-flight AIF work |\n`/analyze` |\nCodebase health audit |\n`/optimize` |\nAPI cost & performance scanner |\n`/template-drift` |\nDetect drift between a project's `.aif/templates/` and the toolkit's |\n\nCore workflow:\n\n```\n/spec → /validate → /architect → /validate → implement → /reflect → /review → merge → /wrapup\n```\n\n| Skill | Description |\n|---|---|\n`/using-aif` |\nMeta-skill routing table — injected at SessionStart |\n`/from-issue` |\nIssue → merge-ready PR orchestrator (classify, route, implement, ship, babysit CI) |\n`/feature-prep` |\nDoes the spec registry need an entry first? Where do tests go? |\n`/grill-feature` |\nAdversarial design review before architectural work |\n`/ship` |\nPre-merge orchestrator — parallel reviewer fan-out → go/no-go → post-deploy verify |\n`/triage-dev` |\nInvestigate your shared dev environment in a configured observability order |\n`/source-driven` |\nRead the authoritative source (config, code, MCP) instead of guessing |\n`/incremental-implementation` |\nThin vertical slices, one repo at a time |\n`/debug` |\nLocal repro and root-cause; Phase 1 = fast deterministic feedback loop |\n`/deprecate` |\nMulti-stage removal across your configured repos |\n`/git-workflow` |\nCommit prefixes (configurable regex), atomic commits, branching, worktrees, PR flow |\n`/handoff` |\nCompact a multi-repo session into a handoff doc |\n`/release-notes` |\nMulti-audience release-notes draft (customer, engineering, executive) from a git tag or range |\n`/dep-update` |\nVetted dependency updates — changelog risk review, isolated branch, test-proven, one PR per batch |\n`/license-audit` |\nSBOM + license compliance — resolve every component's license, judge against `org.license_policy` |\n`/rotate-secrets` |\nProactive secret rotation — expiry gate over the `secrets:` inventory, overlap-pattern rotation, human gate before revoke |\n`/audit-permissions` |\nReview and prune risky standing Claude permission grants in `.claude/settings*.json` (pairs with `aif doctor` 's `permissions-audit` ) |\n`/doc-drift` |\nFind and fix docs made stale by a change — diff-derived surfaces, stale vs missing classification |\n`/threat-model` |\nSTRIDE threat model from a spec/RFC — assets, trust boundaries, refuted threats, mitigation punch list |\n`/expert` |\nCurate a domain expert — path-scoped context distilled from your docs, injected only when a change touches its domain |\n`/add-detector` |\nTemplate: scaffold a module in an extensible service, following your documented pattern |\n`/new-admin-module` |\nTemplate: scaffold a CRUD module (schema → migration → repository → service → handler → registration) |\n\n26 subagents in [ agents/](/highflame-ai/ai-factory/blob/main/agents), each with tier-based model selection rendered by\n\n`aif agents render`\n\n(config: `~/.claude/aif/config.yml`\n\n).**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\n\n[ /expert](/highflame-ai/ai-factory/blob/main/skills/expert/SKILL.md) curates a\n\n**domain expert**: dense context distilled from your own docs and code, stored at\n\n`.aif/experts/<name>.md`\n\n, and injected into a task **only when the change touches that domain**(matched by the expert's\n\n`applies_to`\n\nglobs). Context engineering — React context on a React change, DynamoDB context on a data-access change, neither on unrelated work. `/review`\n\nactivates matching experts automatically. `workspace-CLAUDE.md`\n\nholds facts true everywhere, `references/`\n\nare cross-cutting checklists, lessons are relevance-ranked incidents, experts are path-scoped domain knowledge. The `applies_to`\n\nglobs are also the future compile key for path-scoped rules in other assistants (Copilot `applyTo`\n\n, 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\n\n`{envelope: [read, grep, glob, bash], write: false}`\n\nonce, and `aif compile`\n\nemits it as:**Claude**— validation of`agents/*.md`\n\n`tools:`\n\nfrontmatter (the native layer;`--check`\n\nfails on any agent exceeding its role's envelope), plusper-role settings overlays for headless/CI sessions`compiled/claude/`\n\n**Codex**—sandbox profiles per role`compiled/codex/config.toml`\n\n**Copilot**—paste-in role boundaries (convention — Copilot has no enforcement surface)`compiled/copilot/`\n\n**Cedar**—schema + policies, for orgs enforcing agent capabilities at a gateway`compiled/cedar/`\n\nExceptions are declared in the role file with a reason, never quietly in an agent's own frontmatter. `aif compile --check`\n\nis the drift gate. This is what makes the toolkit's practice portable across agent runtimes rather than Claude-only.\n\nDeterministic gates in [ hooks/](/highflame-ai/ai-factory/blob/main/hooks), wired through each repo's\n\n`.claude/settings.json`\n\n. All wrapped in `if [ -x … ]`\n\nso machines without the install no-op silently.| Hook | Event | Does |\n|---|---|---|\n`session-start-skills.sh` |\nSessionStart | Injects the `/using-aif` routing table |\n`go-format.sh` , `ts-format.sh` , `py-format.sh` , `rust-format.sh` |\nPostToolUse (Edit|Write) | gofmt/goimports, prettier, ruff, rustfmt |\n`secret-scan.sh` |\nPreToolUse (Bash) | Blocks secret exposure and destructive commands |\n`commit-prefix-check.sh` |\nPreToolUse (Bash) | Enforces your CI's commit-subject regex (`AIF_COMMIT_PREFIX_REGEX` → `org.commit_prefix_regex` → Conventional Commits) |\n`precommit-gate.sh` |\nPreToolUse (Bash) | Static analysis on staged files at `git commit` time |\n`session-reflect.sh` |\nStop | One reflection turn → appends warts to the known-warts inbox |\n\n`skills/templates/settings.example.json`\n\nis the shared per-repo `.claude/settings.json`\n\n(permissions + hooks). Maintainers roll it out across a workspace with:\n\n```\ntools/fleet/distribute-settings.sh -n    # dry-run: every git repo in the workspace\nAIF_REPO_GLOB='acme-*' tools/fleet/distribute-settings.sh   # narrow to a repo glob\ntools/fleet/open-settings-prs.sh         # open a PR per modified repo\n```\n\nBoth scripts resolve the workspace root the same way as `install.sh`\n\n: `AIF_WORKSPACE`\n\nenv → machine config `workspace.root`\n\n→ the clone's parent directory.\n\n`/init`\n\ncopies 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.\n\n```\n.aif/\n  ETHOS.md           # copy of the toolkit's ETHOS.md (keeps skills working inside git worktrees)\n  context/           # project overview, architecture, conventions, taxonomy (retrieval tags)\n  specs/             # requirement docs, architecture docs, tasks\n  bugs/              # bug reports\n  knowledge/         # assumptions/ (validated) and lessons/ (learned)\n  templates/         # copies of artifact templates (from this toolkit)\n  partials/          # copies of shared shell snippets (from this toolkit)\n  workflows/         # copies of Dynamic Workflow scripts (from this toolkit)\n  config.yml         # only if you opt into cross-repo coordination (or copy in a preset)\n```\n\nThe toolkit repo contains the **process**; each code repo contains the **artifacts**. Skills read `.aif/config.yml`\n\nat runtime for anything project- or org-specific — `/init`\n\ncreates 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:`\n\nblock.\n\n— the agent-facing guide to this repo (layout, install, house rules) — readable by any AGENTS.md-aware tool;`AGENTS.md`\n\n`CLAUDE.md`\n\nimports it— the principles injected into every AIF skill`skills/ETHOS.md`\n\n— how an org extends the toolkit (skill/agent skeletons, house rules)`examples/`\n\n— on-demand checklists; several are fill-in templates`references/`\n\n— always-loaded workspace context, as a fill-in template`workspace-CLAUDE.md`\n\n— Claude Code power-user guide`tips.md`\n\n— shared POSIX shell functions (forge PR adapter for GitHub/Azure DevOps, id allocation, telemetry)`skills/partials/`\n\n— deterministic Dynamic-Workflow scripts for`skills/workflows/`\n\n`/sprint --workflow`\n\n— the`tools/`\n\n`aif`\n\nCLI, the skill linter, and the opt-in delegation CLIs— stack-shaped starter configs for`skills/presets/`\n\n`.aif/config.yml`\n\n`./catalog.sh`\n\n— terminal inventory of every skill, agent, hook, and reference\n\n```\ncd \"$(readlink ~/.claude/skills)\" && git pull\n```\n\n`git pull`\n\napplies once the toolkit is a published git repo with a remote (or your fork of it). Since `~/.claude/skills`\n\nis a symlink, changes are picked up immediately by every session.\n\nNew skills follow the toolkit conventions (`.aif/context/conventions.md`\n\n): POSIX-only shell in fences, two-level `.aif/`\n\n→ `~/.claude/skills/`\n\nfallback for every asset, PR operations through the forge adapter, org values through config (never hardcoded), `python3 tools/lint-skills/check.py`\n\nclean. New agents get `tier:`\n\nfrontmatter, an entry in `tools/aif/agents_render.py`\n\n, and an `aif agents render`\n\nrun.\n\nMIT — see [ LICENSE](/highflame-ai/ai-factory/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code", "canonical_source": "https://github.com/highflame-ai/ai-factory", "published_at": "2026-07-23 21:45:05+00:00", "updated_at": "2026-07-23 21:52:13.438044+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["Highflame", "ai-factory", "Claude Code", "codeoid"], "alternates": {"html": "https://wpnews.pro/news/show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code", "markdown": "https://wpnews.pro/news/show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code.md", "text": "https://wpnews.pro/news/show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code.txt", "jsonld": "https://wpnews.pro/news/show-hn-ai-factory-a-spec-driven-pipeline-that-stops-ai-agents-rotting-code.jsonld"}}