English | Suomi

AI-Augmented Solo Development Template

A reusable GitHub repository template for human-led, AI-assisted software development. It provides shared context, scoped tasks, repeatable quality gates, and a review workflow while keeping decisions and final approval with the human.

Why this template exists

AI can produce code quickly, but planning, scope control, review, testing, and acceptance still need a managed process. This template provides that process and keeps human judgment involved from the initial goal through approval and release.

Operating model

• Human / Product Owner / final approver: owns the product goal and scope, decides on trade-offs, performs practical acceptance testing, and authorizes commits, merges, and releases.
• ChatGPT / architect and independent reviewer: turns goals into scoped work, defines risks and acceptance criteria, and reviews evidence produced from the repository changes.
• Codex / repository-level implementation agent: inspects repository context, implements the scoped task, runs tests and quality gates, and reports the results without making the final approval decision.
• CI / repeatable quality gate: runs configured checks repeatably and reports failures. Repository rules or branch protection can require those checks before merge. It does not replace architectural review or hands-on testing.

Workflow

Goal
  → architecture, risks and acceptance criteria
  → one scoped Codex task
  → implementation and automated tests
  → structured review package
  → independent review
  → human acceptance testing
  → commit, merge or release

Included capabilities

• Repository-level agent instructions in AGENTS.md
• Shared project brief and architecture context
• Active task management with task templates and history
• A documented Definition of Done
• Security guidance and risk classification
• A structured manual testing record
• PowerShell automation for setup, task creation, validation, context display, and review packaging
• Structured review ZIP generation with changed files, repository context, hashes, Git metadata, and quality-gate logs
• GitHub Actions quality gates
• Technology presets for common project types

Supported presets

• generic
• node-typescript
• python
• flutter
• dotnet

Quick start

A. Use this template on GitHub

Select Use this template on the repository page, create a new repository, clone it, and run the initializer from the repository root.

B. Make a local copy

Copy or extract the template into a new project directory, open PowerShell in the repository root, and run:

pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\initialize-project.ps1 `
  -ProjectName "My Project" `
  -Preset generic `
  -Description "Short project description"

Then complete at least:

• PROJECT_BRIEF.md
• docs/ARCHITECTURE.md
• tasks/CURRENT_TASK.md
• project.config.json

Copy CHATGPT_PROJECT_INSTRUCTIONS.md into the ChatGPT project instructions. Codex must read AGENTS.md before implementation work begins.

Core commands

# Initialize the template for a project
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\initialize-project.ps1 `
  -ProjectName "My Project" `
  -Preset generic `
  -Description "Short project description"

# Archive the current task and create a new active task
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\new-task.ps1 `
  -Title "Task title"

# Validate required template files and configuration
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-project.ps1

# Run the quality gates configured in project.config.json
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\run-quality-gates.ps1

# Create a structured review ZIP and run quality gates first
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\create-review-package.ps1 -RunQualityGates

# Print the configured repository context files
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\show-context.ps1

Repository structure

.
├── .github/                 # Issue, pull request, and CI configuration
├── artifacts/               # Local quality-gate and review-package outputs
├── docs/                    # Architecture, workflow, security, review, and test guidance
│   └── decisions/           # Architecture decision records
├── scripts/                 # PowerShell workflow automation
├── tasks/                   # Active task, task template, and completed-task history
├── templates/presets/       # Technology-specific quality-gate presets
├── AGENTS.md                # Repository instructions for implementation agents
├── PROJECT_BRIEF.md         # Product and project context
├── project.config.json      # Template settings and configured quality gates
├── README.md                # English repository landing page
└── README.fi.md             # Finnish repository landing page

The src/, tests/, config/, and infra/ directories are generic placeholders to adapt to the selected technology stack.

Safety principles

• An AI agent does not approve its own work.
• No commit, push, merge, or release is performed without explicit human approval.
• Secrets must not be committed or included in review packages. Known secret-file patterns are ignored or blocked by the repository configuration.
• Changes remain small and scoped to the active task.
• Failed or skipped tests are reported explicitly.
• Project-specific business logic is not added to the generic template.

Documentation

• Finnish README
• Start here
• Repository agent instructions
• Project brief
• ChatGPT project instructions
• AI-assisted workflow
• Architecture
• Definition of Done
• Security
• Test strategy
• Finnish usage guide (Word document)

Scope

This template is not:

• A fully autonomous software factory
• A finished application tied to a specific framework
• A replacement for human review or acceptance testing

Status

The template is developed based on experience gained from practical software projects.