AdpBer — Agent Spec-Driven Project Boilerplate Creator

AdpBer scaffolds the boilerplate for a new agent spec-driven project. Point it at a path on disk, pick a template, and it lays down the directory structure, the minimum harness, and the spec-driven document set an AI agent needs to reason about and operate within the project from day one.

"Spec-driven" is the point: a generated project doesn't start from an empty repo and a chat prompt. It starts from a connected set of documents — a problem definition, an architecture spec, an implementation plan, an engineering-discipline guide, and an Architecture Decision Record (ADR) log — that an agent reads first and works from. The code follows the spec; the spec isn't reverse-engineered from the code.

What it does

1. Creates the project directory at the path you specify (creating it if it doesn't exist).
2. Lays down the minimum harness — the agent-instructions file (CLAUDE.md) and the structural scaffolding common to every agent project.
3. Populates the spec-driven document set from templates — problem definition, specs, plan, engineering discipline, and an ADR folder are written from templates/ rather than regenerated from scratch each time.
4. Template-driven — domain-specific templates live in templates/<name>/ and are selected at init time. Each subdirectory of templates/ is one selectable template; its folder name is the --template argument. The current built-in template (project-structure) targets the ML/predictive-agent class (offline processing → staging → production, with artifact promotion, parity invariants, and safety control). A general-purpose template (workflow agents, integration agents, etc.) is planned.

Status: the adpber CLI is not implemented yet. The substance of this repo today is the template set under templates/project-structure/; the CLI that copies and fills it is still to be built.

Usage

adpber init <project-path> [--template <name>]

Argument	Description
<project-path>	Absolute or relative path where the new project will be created. AdpBer creates the directory if it does not already exist.
--template <name>	Template subdirectory to use from templates/. The folder name is the template identifier (e.g. project-structure). Defaults to project-structure if omitted.

Example

adpber init ~/projects/my-agent --template project-structure

This creates ~/projects/my-agent/ and populates it with the spec-driven harness.

The spec-driven document set

Every generated project receives a cross-linked set of documents. They reference each other by section and relative path, so an agent can navigate from house rules to the decision that justifies them:

File	Role
CLAUDE.md	Agent-instructions file — house rules, ADR policy, and engineering discipline the agent follows.
docs/problem.md	Problem definition, stakeholders, and success criteria — the why.
docs/specs.md	Framework-neutral architecture specification — modules, contracts, and invariants.
docs/plan.md	Milestone-driven implementation plan — locked decisions, workstreams, and gates.
docs/engineering-discipline.md	CI invariants, selective-TDD scope, and ADR policy.
docs/decisions/	ADR log with a Michael-Nygard-style template for recording consequential decisions.

Templates use {-Placeholder-} slots (e.g. {-Project-Name-}, {-Date-}) that are filled in at init time. Additional scaffolding (CI skeleton, pre-commit config, etc.) is included depending on the template selected.

Repository layout

Adpber/
├── templates/
│   └── project-structure/              # Reference layout copied into every generated project
│       ├── CLAUDE.md                   # Agent-instructions template
│       ├── src/                        # Generated project's source dir (empty placeholder)
│       └── docs/
│           ├── problem.md              # Problem-definition / stakeholder template
│           ├── specs.md                # Architecture spec template
│           ├── plan.md                 # Implementation plan template
│           ├── engineering-discipline.md   # CI invariants, TDD scope, ADR policy template
│           └── decisions/              # ADR folder + Nygard-style template (README.md)
└── README.md

Note: everything under templates/project-structure/ is content for generated projects. The heavyweight discipline those templates describe (CI gates, milestones, invariants) governs the projects AdpBer produces — not AdpBer itself.

Contributing

• Branch off main; merge only via PR with green CI. Don't commit directly to main.
• PR titles follow Conventional Commits.