AI Feature Builder

A portable, architecture-agnostic toolkit for building features with AI coding agents — covering the whole cycle: understand the code, spec the work, implement it, ship it, track it. Install only the groups you need; the builder adapts its output to Claude Code, Cursor, or a generic agent format.

Core ships skills that work in any project, regardless of stack or architecture: dev-helpers to read existing code, spec-driven development to plan and implement, git workflows to ship, and Trello integration to track. Architecture-specific skills and layer rules come from packs — opt-in bundles you install when your project follows a specific design pattern.

Requirements

• node >= 18 (ESM)
• git
• bash

Tested on macOS and Linux (the shell scripts avoid GNU/BSD-only flags — e.g. no sed -i, and mktemp/timeout calls handle both coreutils flavors). On Windows, run everything through WSL or Git Bash; the scripts do not run under cmd.exe or native PowerShell.

Quickstart

# 1. Clone the builder (or add as a git submodule)
git clone https://github.com/your-org/ai-feature-builder.git ~/tools/ai-feature-builder

# 2. Create your target config
#    Creates ai-feature-builder.config.json IN YOUR TARGET PROJECT — customize it in step 3
#    Installing an architecture pack? Add --pack <name> to promote that pack's config keys
#    (they ship suffixed and inert, so a core-only project never carries them)
~/tools/ai-feature-builder/aifb.sh init --target /path/to/your-project

# 3. Edit ai-feature-builder.config.json to match your project layout
#    See docs/10-usage.md for the full key reference
#    gitignore is automatic: init/add/remove/update keep a managed block in your project's
#    .gitignore that excludes ai-feature-builder.config.json, .ai-feature-builder/, and the generated .claude/+.cursor/
#    files (per-checkout, like .env; each teammate regenerates their own). To commit them
#    instead, set git.commit_generated=true in ai-feature-builder.config.json.

# 4. Install the core skill groups you want
~/tools/ai-feature-builder/aifb.sh add spec-workflow --target /path/to/your-project

# 5. (Optional) Install an architecture pack
~/tools/ai-feature-builder/aifb.sh add rules-layers skills-scaffold arch-check --pack clean-architecture --target /path/to/your-project

# 6. (Optional) Add the idioms for your stack — greenfield code, or layers with no example yet
~/tools/ai-feature-builder/aifb.sh add idioms --pack clean-arch-python-fastapi --target /path/to/your-project

After step 4 your project's .claude/ and .cursor/ trees contain ready-to-use skills and rules, resolved against the values in your ai-feature-builder.config.json.

Core Groups

The core groups make no assumption about your project's architecture or stack.

Group	Items
dev-helpers	explain, inspect, update-docs, qa-platform
git	commit, merge-request
spec-workflow	analysis, spec, implement, cleanup, run-spec †, junit-to-md †
trello	trello-card, trello-archive

† run-spec and junit-to-md are scripts, not skills: they are copied verbatim into <target>/scripts/ai-feature-builder/ (no placeholder generation — they read ai-feature-builder.config.json at run time). run-spec.sh is the headless orchestrator the spec/implement skills refer to; it calls junit-to-md.py itself for the final test-triage artifact. Run it from your project root: scripts/ai-feature-builder/run-spec.sh "<feature>" --preview.

Individual items can be installed by id: aifb.sh add explain commit.

Pack Groups

Packs add architecture-specific skills (and rules, where a pattern needs them). Install them when your project follows the matching pattern.

Pack	Group	Items
clean-architecture	rules-layers	dependency-rule, domain-layer, application-layer, infrastructure-layer, presentation-layer, boundary-dtos, testing
clean-architecture	skills-scaffold	add-entity, add-usecase, add-adapter, add-endpoint
clean-architecture	arch-check	check-arch
clean-arch-python-fastapi	idioms	idioms-python-fastapi

Install with --pack <name>: aifb.sh add rules-layers skills-scaffold arch-check --pack clean-architecture.

clean-architecture is stack-agnostic: it states the invariants of a layered architecture and takes its topology from your layers config map, so it installs on a project in any language. It ships no code snippets. The how — how immutability, injection, and error mapping are written in a given stack — lives in an idiom pack (clean-arch-python-fastapi), which is optional and matters mainly for greenfield code, where the skills' "read a sibling first" step has no sibling to read.

See packs/clean-architecture/README.md for the required directory layout and a checklist for authoring your own pack.

Commands

Command	Action
aifb.sh init [--pack <name>]	Copy ai-feature-builder.config.example.json → ai-feature-builder.config.json in the target. With --pack, also promote that pack's suffixed config blocks to live top-level keys (additive, never clobbering)
aifb.sh add <group|id> … [--pack <name>]	Generate and copy chosen skills/rules into the target
aifb.sh remove <group|id> …	Delete only the builder-managed files for the given ids
aifb.sh list	Print installed items from the ledger
aifb.sh update	Re-run add for every installed item (idempotent)
aifb.sh purge	Uninstall the builder entirely: remove every ledger-tracked file, delete .ai-feature-builder/ + ai-feature-builder.config.json, strip the managed .gitignore block

All commands accept --target DIR (default: current directory). Full reference: docs/10-usage.md.

How It Works

src/skills/<id>/skill.md               ─┐
src/rules/<id>/rule.md                 ─┤
packs/<pack>/skills/<id>/skill.md   ─┤─► generate.mjs ─► .claude/ + .cursor/
packs/<pack>/rules/<id>/rule.md     ─┘
ai-feature-builder.config.json

scripts/run-spec.sh, scripts/junit-to-md.py ──(verbatim copy)──► scripts/ai-feature-builder/

Each skill and rule has a single canonical source with neutral placeholders ({{prefix}}, {{spec_dir}}, …). The generator resolves them against your ai-feature-builder.config.json and emits the correct format for each agent (Claude skill frontmatter, Cursor .mdc frontmatter, etc.). Items of type script skip generation entirely: they are copied byte-for-byte into scripts/ai-feature-builder/ and read ai-feature-builder.config.json themselves at run time.

The installer tracks every file it wrote in .ai-feature-builder/installed.json. It never touches files it did not create — the one exception is your .gitignore, where it maintains a single delimited # >>> ai-feature-builder … <<< block (excluding the generated files by default) and leaves the rest of the file untouched. Set git.commit_generated: true to drop that block. See docs/10-usage.md.

Documentation

Doc	Contents
docs/00-conventions.md	Placeholder contract, config schema, canonical file format, banned-token list
docs/10-usage.md	Full command reference, config key guide, group→skill map
docs/20-flow-examples.md	Worked end-to-end install and update flows
packs/clean-architecture/README.md	Pack-authoring walkthrough: required layout, manifest contract, how to build your own pack
packs/clean-arch-python-fastapi/README.md	Idiom-pack walkthrough: what belongs in one, and how to write one for another stack

Testing / CI

The acceptance gate is test/e2e.sh, backed by the reusable de-branding guard check.sh.

# Full end-to-end gate: init -> add every group into a scratch target -> assert the
# generated .claude/+.cursor/ trees are clean, coverage is complete, and frontmatter is faithful.
bash test/e2e.sh

# De-branding guard, standalone. Scan any directory for banned project tokens and
# unresolved {{...}} placeholders. Exit non-zero on any hit. The token list is a config
# file: copy banned-tokens.example.txt to banned-tokens.txt (gitignored) and list YOUR
# project's values — company/product names, internal hosts, hardcoded branches.
# Full format and resolution order: docs/00-conventions.md §4.
./check.sh <dir>
./check.sh --tokens my-tokens.txt <dir>
./check.sh --allow-placeholders src    # scan canonical sources (placeholders are expected there)

Run both in CI: check.sh fails the build on any banned token or {{…}} residue, and e2e.sh proves the whole generate→install pipeline stays clean across every group.