Usage

This tool is a command-line application. It's purpose is to scaffold new Git repositories with standard structure, boilerplate, and coding guidelines for C++, Go, and Java projects.

It also aims to foster an AI-Augmented Spec Driven Development approach, where specifications (e.g., ADRs, OpenAPI, BDD feature files) are the single source of truth and the codebase is automatically kept in sync with them.

These are the supported programming languages and project types:

Language	Project Types	CI
C++	CLI Tool, Library, (Micro) Service	GitHub Actions, GitLab CI
Go	CLI Tool, Library, (Micro) Service	GitHub Actions, GitLab CI
Java	Library, (Micro) Service	GitHub Actions, GitLab CI

Claude Code configuration (CLAUDE.md, .claude/) is always generated. GitHub Copilot, GitLab Duo, and Cursor configuration is generated on request via --assistant.

What do I Get by Using this Tool?

• Quickly starting new projects without caring for the boiler plate too much.
• A well-structured codebase with a clear separation of concerns, following best practices and architectural guidelines.
• A set of pre-configured CI pipelines for GitHub Actions and GitLab CI, ensuring code quality and consistency.
• GitHub and GitLab Pages will be created from the specifications, providing easy access to documentation and specifications for all stakeholders.
• A development workflow that encourages writing specifications first, and then using AI coding assistants like Claude to implement the code based on those specifications.
• A set of guidelines and rules for both human developers and AI coding assistants to follow, ensuring that the codebase remains consistent, maintainable, and aligned with the project's goals.

Pre-requisites

The repo executable is in your PATH, or GO_PATH, so that it can be executed on the command line.

Workflow

Starting a Project

1. Create a new repository on GitHub, GitLab, or your preferred Git hosting platform.
2. Clone the repository to your local machine and navigate into it.
3. Run the repo init command to scaffold the project structure and boilerplate code. For example:

repo init --artifactname "insurance-accounts" --ci gitlab \
          --description "Insurance account backend service." \
          --language go --name "Insurance Account Service" \
          --targetpath .

This will set up a new Go microservice project with Claude Code configuration and GitLab CI. To also add GitHub Copilot and Cursor support, add --assistant copilot --assistant cursor.

Claude Code configuration is always generated. The --assistant flag is optional and may be repeated or comma-separated. Valid values: copilot, duo, cursor.

1. After the scaffolding is complete, you can start working on your project by following the specifications and using the provided commands and guidelines.

Working on Features

To benefit from the full potential of this tool, it's recommended to follow an AI augmented, spec-driven development approach:

1. For every new feature, start by writing the specifications first:
2. Document architectural decisions (ADR) you might have made.
3. Write BDD feature files to define the expected behavior of your system.
4. Define your API contract, e.g. openAPI or other format suitable for your project. You can do this manually, or instruct Claud to support you by means of the /endpoint command.
5. Update your domain model and business rules in to reflect the new feature.
6. Also keep the glossary up to date.
7. All of the above is important for human developers, testers, and other stakeholders, but also for AI coding assistants like Claude. By providing clear and precise specifications, you enable the AI to generate code that is more likely to be correct and aligned with your intentions.
8. You may also ask Claude to help you with the specification. For example, you could ask Claude for industry best practices. However, you are in charge. Always challange what the AI is proposing.
9. Next, create a prompt to tell Claude to implement the code for you, based on the specifications you just created:
10. Very briefly and focused describe the purpose, context, what to do, and what not to do.
11. The prompt should also include instructions to write tests for the new code, and to update existing tests if needed.
12. As with the specifications, you can ask Claude for help with the prompt.
13. Use Claudes Plan mode.
14. Once the prompt is ready, execute it and let Claude generate the code for you.
15. Use Claudes Plan mode. Verify the plan before executing it.
16. Review the generated code, documentation, and tests. Execute the tests. The prepopulated repos already has Makefile targets for testing, architecture checks, linting, and other quality checks.

Here is an example of such a prompt:

Implement the GET /accounts/{account-id} endpoint for the insurance account service.

**Context**
The endpoint retrieves a single insurance account by its ID.
All relevant specifications are already written and are the single source of truth:
- specs/features/UC012-get_account.feature       — expected behaviour (BDD)
- specs/APIs/provided/openapi.yaml               — request/response contract
- specs/domain_model/domain_model.md             — Account aggregate and value objects
- specs/domain_model/business_rules.md           — visibility and access rules

**What to do**
- Implement the use case, domain logic, and infra layer for this endpoint.
- Wire the HTTP handler following the existing handler conventions in this codebase.
- Write unit tests for the use case and domain logic.
- Ensure the BDD scenario in UC012-get_account.feature passes end-to-end.

**What NOT to do**
- Do not change the OpenAPI contract — implement strictly against it.
- Do not add fields, error codes, or behaviours not covered by the specs.
- Do not modify existing use cases, domain objects, or handlers unrelated to this endpoint.
- Do not introduce new dependencies without noting them in the plan.

**Spec consistency**
If you discover a gap or ambiguity in the specs during implementation, stop and report it
instead of making an assumption. Do not silently diverge from the specs.

Under Spec consistency you may miss an instruction like "Always keep the specs and codebase in sync." This is because the folder .claude/rules/spec_consistency.md already contains detailed instructions for the Spec-Consistency Guardian.

Constraints/Requirements

• The specification has be complete but minimal.
• The specification has to be precise and unambigious.
• Promts have be complete but minimal.
• Promts have be precise and unambigious.
• Always challange the AI.
• Always use Claudes Plan mode.
• Review the plan.
• Review the generated code.
• Review the tests.
• Human developers and AI coding assistants have to respect the guidelines given (architecture guidelines, coding guidelines, API design guidelines, data modeling guidelines, etc.).