From c4cfe78090d216571d01ccd7fdac375237d38dd9 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 26 Mar 2026 14:32:21 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20Week=201=20setup=20=E2=80=94=20CLAUDE.m?= =?UTF-8?q?d,=20project=20structure,=20CI,=20and=20legacy=20archival?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Create CLAUDE.md as the single source of truth for AI agents. Set up specs/, agents/, quality/, docs/ directory structure. Add GitHub Actions CI workflow with ShellCheck and markdownlint. Archive legacy 2016-2019 Docker CI/CD infrastructure to legacy/. Modernize README.md and .gitignore. Co-authored-by: montoyaedu <1033682+montoyaedu@users.noreply.github.com> Agent-Logs-Url: https://github.com/ethiclab/buildmachine/sessions/a8fac7dc-b0df-4e43-975c-dae0dce2b3b0 --- .github/workflows/ci.yml | 28 +++ .gitignore | 18 ++ CLAUDE.md | 171 ++++++++++++++++ README.md | 183 ++---------------- agents/README.md | 26 +++ docs/workflow-9-phases.md | 94 +++++++++ legacy/README.md | 26 +++ backup.sh => legacy/backup.sh | 0 backup_all.sh => legacy/backup_all.sh | 0 backup_jenkins.sh => legacy/backup_jenkins.sh | 0 backup_nexus.sh => legacy/backup_nexus.sh | 0 backup_sonar.sh => legacy/backup_sonar.sh | 0 build.sh => legacy/build.sh | 0 connect.sh => legacy/connect.sh | 0 .../create_host_nexus_user.sh | 0 create_volumes.sh => legacy/create_volumes.sh | 0 .../docker-compose.yml | 0 .../env-devel-local.sh | 0 remove_volumes.sh => legacy/remove_volumes.sh | 0 restore_all.sh => legacy/restore_all.sh | 0 .../restore_jenkins.sh | 0 restore_nexus.sh => legacy/restore_nexus.sh | 0 restore_sonar.sh => legacy/restore_sonar.sh | 0 .../show_initial_jenkins_password.sh | 0 start.sh => legacy/start.sh | 0 stop.sh => legacy/stop.sh | 0 quality/gates.md | 45 +++++ specs/0001-setup-ci.md | 25 +++ specs/README.md | 17 ++ 29 files changed, 471 insertions(+), 162 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 CLAUDE.md create mode 100644 agents/README.md create mode 100644 docs/workflow-9-phases.md create mode 100644 legacy/README.md rename backup.sh => legacy/backup.sh (100%) rename backup_all.sh => legacy/backup_all.sh (100%) rename backup_jenkins.sh => legacy/backup_jenkins.sh (100%) rename backup_nexus.sh => legacy/backup_nexus.sh (100%) rename backup_sonar.sh => legacy/backup_sonar.sh (100%) rename build.sh => legacy/build.sh (100%) rename connect.sh => legacy/connect.sh (100%) rename create_host_nexus_user.sh => legacy/create_host_nexus_user.sh (100%) rename create_volumes.sh => legacy/create_volumes.sh (100%) rename docker-compose.yml => legacy/docker-compose.yml (100%) rename env-devel-local.sh => legacy/env-devel-local.sh (100%) rename remove_volumes.sh => legacy/remove_volumes.sh (100%) rename restore_all.sh => legacy/restore_all.sh (100%) rename restore_jenkins.sh => legacy/restore_jenkins.sh (100%) rename restore_nexus.sh => legacy/restore_nexus.sh (100%) rename restore_sonar.sh => legacy/restore_sonar.sh (100%) rename show_initial_jenkins_password.sh => legacy/show_initial_jenkins_password.sh (100%) rename start.sh => legacy/start.sh (100%) rename stop.sh => legacy/stop.sh (100%) create mode 100644 quality/gates.md create mode 100644 specs/0001-setup-ci.md create mode 100644 specs/README.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..80c878f --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,28 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Lint shell scripts with ShellCheck + uses: ludeeus/action-shellcheck@2.0.0 + with: + scandir: './legacy' + severity: warning + + - name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + globs: '**/*.md' diff --git a/.gitignore b/.gitignore index 49e0640..b96dc5f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,20 @@ +# Legacy /example/ /backup/ + +# OS +.DS_Store +Thumbs.db + +# Editors +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Node (for local linting tools) +node_modules/ + +# Temporary files +/tmp/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..053a628 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,171 @@ +# CLAUDE.md — Buildmachine Project Instructions + +## Identity + +**Buildmachine** is an AI-driven virtual software house. It uses AI agents (Claude, Codex, Gemini) to design, build, test, review, and ship software. This repository is the control plane: it contains the workflows, conventions, and tooling that orchestrate AI-powered development. + +The name comes from the original 2016 project — a Docker-based CI/CD machine. The mission is the same, only the workers have changed: from Jenkins pipelines to AI agents. + +## Project Structure + +``` +. +├── CLAUDE.md # This file — the single source of truth for AI agents +├── README.md # Human-readable project overview +├── specs/ # Task specifications (input for AI agents) +│ └── example.md # Template for a task spec +├── agents/ # Agent configurations and prompts +│ └── README.md # How agents are organized +├── quality/ # Quality gate definitions and scripts +│ └── gates.md # Quality gate checklist +├── .github/ +│ └── workflows/ +│ └── ci.yml # GitHub Actions CI pipeline +├── legacy/ # Archived 2016-2019 Docker CI/CD setup +│ ├── docker-compose.yml +│ └── *.sh +└── docs/ # Extended documentation + └── workflow-9-phases.md # The 9-phase AI development workflow +``` + +## Conventions + +### Language +- Documentation and specs: **Italian or English** (match the language of the task/issue). +- Code, configs, commit messages, branch names: **English only**. +- CLAUDE.md: **English** (agents work best in English). + +### Commits +- Use [Conventional Commits](https://www.conventionalcommits.org/): `type(scope): description` +- Types: `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `ci` +- Keep commits atomic — one logical change per commit. + +### Branches +- `main` — stable, protected +- `feat/` — feature work +- `fix/` — bug fixes +- `chore/` — maintenance + +### Files +- Markdown for all documentation and specs. +- YAML for configuration (GitHub Actions, Docker Compose). +- Shell scripts must use `#!/usr/bin/env bash`, `set -euo pipefail`, and be linted with ShellCheck. + +## Quality Gates + +Every change must pass these gates before merging to `main`: + +| # | Gate | Tool | Blocking? | +|---|------|------|-----------| +| 1 | **Lint** | ShellCheck (shell), markdownlint (docs) | Yes | +| 2 | **Build** | `docker compose build` (if applicable) | Yes | +| 3 | **Test** | Project-specific test suite | Yes | +| 4 | **Security scan** | CodeQL / dependency audit | Yes | +| 5 | **AI code review** | Claude code_review or CodeRabbit | Advisory | + +A PR cannot be merged if any blocking gate fails. Advisory gates produce feedback that should be addressed but don't block the merge. + +## The 9-Phase AI Development Workflow + +This is the standard workflow for every task processed by AI agents: + +### Phase 1 — Spec +Write a clear task specification in `specs/`. Include: goal, constraints, acceptance criteria, and examples. **This is human work** — it's the highest-leverage activity. + +### Phase 2 — Explore +The agent explores the codebase to understand context, existing patterns, and relevant files. No changes are made. + +### Phase 3 — Plan +The agent produces a checklist of minimal, surgical changes. The plan is reported via `report_progress` before any code is written. + +### Phase 4 — Implement +Small, incremental changes. Each meaningful unit of work is committed and pushed separately. + +### Phase 5 — Lint +All linters run. Issues are fixed immediately. + +### Phase 6 — Test +All existing tests run. New tests are written for new behavior. Regressions are unacceptable. + +### Phase 7 — Security +CodeQL and dependency audits run. Vulnerabilities in changed code are fixed. False positives are documented. + +### Phase 8 — Review +AI code review runs. Valid feedback is addressed; a second review runs if significant changes were made. + +### Phase 9 — Ship +PR is finalized with a clean description. All gates pass. Ready for human approval and merge. + +## How to Write a Good Spec (`specs/*.md`) + +```markdown +# Task Title + +## Goal +One sentence describing what needs to be done. + +## Context +Why this task matters. Link to related issues or docs. + +## Constraints +- What must NOT change +- Performance requirements +- Compatibility requirements + +## Acceptance Criteria +- [ ] Criterion 1 +- [ ] Criterion 2 + +## Examples +Show input → expected output, or before → after. + +## Notes +Anything else the agent should know. +``` + +## Commands + +### CI locally +```bash +# Lint shell scripts +shellcheck legacy/*.sh + +# Lint markdown +npx markdownlint-cli2 "**/*.md" + +# Run full CI +act -j lint # requires nektos/act +``` + +### Docker (legacy) +```bash +cd legacy/ +docker compose up -d +docker compose down +``` + +## Agent-Specific Instructions + +### For Claude (Copilot Coding Agent) +- Always read this file first. +- Follow the 9-phase workflow. +- Use `report_progress` after each phase. +- Keep changes minimal and surgical. +- Never remove or weaken existing tests. +- Commit messages follow Conventional Commits. + +### For Codex (async tasks) +- Same conventions as Claude. +- Suited for well-defined, isolated tasks (e.g., "add tests for X", "refactor Y"). +- Task specs must be self-contained — Codex has no session memory. + +### For Gemini (large-context analysis) +- Use for codebase-wide analysis, large refactors, or architectural review. +- Output should be a report in `docs/`, not direct code changes. + +## What NOT to Do +- Don't add dependencies without checking for vulnerabilities first. +- Don't create helper scripts in the repo root — use `/tmp` for temporary files. +- Don't modify `CLAUDE.md` without human approval. +- Don't commit secrets, credentials, or API keys. +- Don't ignore linter or security warnings without documenting why. diff --git a/README.md b/README.md index cf4e75f..b7c5431 100644 --- a/README.md +++ b/README.md @@ -1,172 +1,31 @@ -Getting started -=============== +# Buildmachine -Install docker and docker-compose for your platform +An AI-driven virtual software house. AI agents design, build, test, review, and ship software — humans write specs and approve merges. -# Install http proxy +## Quick Start -https://github.com/ethiclab/docker-nginx-http-proxy +1. Read [`CLAUDE.md`](CLAUDE.md) — the single source of truth for how this project works +2. Write a task spec in [`specs/`](specs/) +3. Let an AI agent implement it following the [9-phase workflow](docs/workflow-9-phases.md) +4. Review, approve, merge -Configure default settings -========================== +## Project Structure -Create a file with the same content of env-devel-local.sh and the modify its content -according to your system. +| Directory | Purpose | +|-----------|---------| +| `specs/` | Task specifications (input for AI agents) | +| `agents/` | Agent configurations and roles | +| `quality/` | Quality gate definitions | +| `docs/` | Extended documentation | +| `.github/workflows/` | CI/CD with GitHub Actions | +| `legacy/` | Original 2016-2019 Docker CI/CD setup (archived) | -````` - export COMPOSE_PROJECT_NAME=buildmachine - export DOMAIN=local - export ENV=devel - export PROXY_PORT=80 -````` +## Quality Gates -You will need to create the folders for JENKINS_HOME_PATH, SONARDB_DATA_PATH, NEXUS_WORK_PATH and -ensure that the current user has read/write access to them. +Every PR must pass: **Lint** → **Build** → **Test** → **Security** → **AI Review** -Applying default settings -========================= +See [`quality/gates.md`](quality/gates.md) for details. -````` - . env-devel-local.sh -````` +## History -If you create a custom file you will need to apply that file instead of env-devel-local.sh before -building or starting the ecosystem trough docker-compose. - -Building -======== - -````` - docker-compose build -````` - -Starting -======== - -````` - docker-compose up -d -````` - -Stopping -======== - -````` - docker-compose down -````` - -Name resolution -=============== - -In order to access your services by name, modify your dns entries or your /etc/hosts entries like the following entries. (example provided for localhost) - -````` - 127.0.0.1 localhost web-devel.local jenkins-devel.local nexus-devel.local sonar-devel.local seleniumhub-devel.local -````` - -then you should have access to the following urls: - -* http://web-devel.local -* http://seleniumhub-devel.local -* http://sonar-devel.local -* http://nexus-devel.local -* http://jenkins-devel.local - -Accessing jenkins for the first time -==================================== - -When you first access your jenkins host you will be asked for an initial password. - -execute the following command to discover the password and choose the installations of the recommended plugins. - -````` - ./show_initial_jenkins_password.sh -````` - -Remember that this command needs to be edited if you modify the name of the folder containing docker-compose.yml file. - -Customizing -=========== - -If you want to customize the access urls, you can create another file tha looks like the env-devel-local.sh and you can apply it to the session before building and launching your docker-compose ecosystem. - -For instance, if you want your urls look like: - -* http://web-prod.mycompany.com:8888 -* http://seleniumhub-prod.mycompany.com:8888 -* http://sonar-prod.mycompany.com:8888 -* http://nexus-prod.mycompany.com:8888 -* http://jenkins-prod.mycompany.com:8888 - -You can create a file env-prod-mycompany.com-8888.sh with the following content: - -````` - export COMPOSE_PROJECT_NAME=buildmachine - export DOMAIN=mycompany.com - export ENV=prod - export PROXY_PORT=8888 -````` - -And then: - -apply that file to the current shell session - -````` - . env-prod-mycompany.com-8888.sh - docker-compose build - docker-compose up -````` - -do not forget to update your name resolution records - -Backup -====== - -With all the ecosystem started, just issue the following command: - -````` -. env-devel-local.sh -./backup_all.sh -````` - -This will create a backup folder and within it a folder will be created with the name: YYYY-MM-DD_HHmmss - -There three files will be created: - -1. jenkins.tar.gz -2. nexus.tar.gz -3. sonar.sql - -Restore -======= - -In order to simulate a new system, we will stop the current ecosystem and will delete the shared volumes. - -````` -. env-devel-local.sh -./stop.sh -./remove_volumes.sh -````` - -At this point, before we start a new ecosystem we will restore a saved state: - -````` -. env-devel-local.sh -./create_volumes.sh -./restore_all.sh backup/YYYY-MM-DD_HHmmss -````` - -Then we can start the system normally: - -````` -. env-devel-local.sh -./start.sh -````` - -Scale -===== - -You can scale services by issuing: - -````` -docker-compose scale web=2 -````` +This project started in 2016 as a Docker Compose-based CI/CD environment (Jenkins, Nexus, SonarQube, Selenium). The original infrastructure is preserved in [`legacy/`](legacy/) for reference. In 2026, it was reborn as an AI-driven software house — same mission (build software), different workers (AI agents instead of Jenkins pipelines). diff --git a/agents/README.md b/agents/README.md new file mode 100644 index 0000000..c503982 --- /dev/null +++ b/agents/README.md @@ -0,0 +1,26 @@ +# Agents + +This directory contains configuration and system prompts for AI agents used in the buildmachine software house. + +## Agent Roles + +| Agent | Model | Role | Best For | +|-------|-------|------|----------| +| **Builder** | Claude | Primary coding agent | Feature implementation, bug fixes, refactoring | +| **Reviewer** | Claude / CodeRabbit | Code review | PR review, quality feedback | +| **Architect** | Gemini | Analysis & design | Large-context analysis, architecture decisions | +| **Worker** | Codex | Async task execution | Isolated, well-defined tasks | + +## How Agents Collaborate + +1. **Human** writes a spec in `specs/` +2. **Builder** implements the spec following the 9-phase workflow +3. **Reviewer** reviews the PR +4. **Human** approves and merges + +For complex tasks: +1. **Human** writes a high-level spec +2. **Architect** breaks it into sub-tasks and produces `specs/` for each +3. **Builder** or **Worker** implements each sub-task +4. **Reviewer** reviews each PR +5. **Human** approves and merges diff --git a/docs/workflow-9-phases.md b/docs/workflow-9-phases.md new file mode 100644 index 0000000..ae68b7b --- /dev/null +++ b/docs/workflow-9-phases.md @@ -0,0 +1,94 @@ +# The 9-Phase AI Development Workflow + +## Overview + +Every task in the buildmachine software house follows a structured 9-phase workflow. This ensures consistency, quality, and traceability regardless of which AI agent or human performs the work. + +## Phases + +### Phase 1 — Spec ✍️ +**Who**: Human +**What**: Write a task specification in `specs/` +**Output**: A markdown file with goal, constraints, acceptance criteria, and examples + +This is the most important phase. The quality of the spec determines the quality of everything that follows. AI agents cannot write their own specs — they need clear human intent. + +### Phase 2 — Explore 🔍 +**Who**: AI Agent +**What**: Read the codebase, understand context, identify relevant files and patterns +**Output**: Internal understanding (no changes to the repo) + +The agent reads `CLAUDE.md`, the spec, and explores the codebase. No changes are made. The agent builds a mental model of what exists and what needs to change. + +### Phase 3 — Plan 📋 +**Who**: AI Agent +**What**: Produce a minimal-change checklist +**Output**: A checklist reported via `report_progress` + +The plan should be surgical — the smallest set of changes that fully addresses the spec. Over-engineering is a defect. + +### Phase 4 — Implement 🔨 +**Who**: AI Agent +**What**: Make the changes, one commit at a time +**Output**: Code changes committed and pushed + +Each commit is atomic and follows Conventional Commits. Progress is reported after each meaningful unit of work. + +### Phase 5 — Lint 🧹 +**Who**: CI (automated) +**What**: Run all linters +**Output**: Clean lint report + +If linting fails, the agent fixes the issues immediately before proceeding. + +### Phase 6 — Test 🧪 +**Who**: AI Agent + CI +**What**: Run existing tests, write new tests for new behavior +**Output**: All tests pass, no regressions + +Removing or weakening tests is never acceptable. + +### Phase 7 — Security 🔒 +**Who**: CI (automated) + AI Agent +**What**: CodeQL scan, dependency audit +**Output**: No new vulnerabilities, or documented exceptions + +Vulnerabilities in changed code must be fixed. False positives are documented. + +### Phase 8 — Review 📝 +**Who**: AI Reviewer +**What**: Automated code review +**Output**: Review feedback addressed + +The AI reviewer checks for correctness, style, security, and adherence to conventions. Valid feedback is incorporated; a second review runs if significant changes were made. + +### Phase 9 — Ship 🚀 +**Who**: Human +**What**: Final approval and merge +**Output**: Changes merged to `main` + +The human reviews the PR description, checks that all gates pass, and merges. This is the human's quality checkpoint. + +## Diagram + +``` +Human AI Agent CI + │ │ │ + ├─ 1. Spec ─────►│ │ + │ ├─ 2. Explore │ + │ ├─ 3. Plan │ + │ ├─ 4. Implement│ + │ │ ├─ 5. Lint + │ │ ├─ 6. Test + │ │ ├─ 7. Security + │ │ ├─ 8. Review + ├─ 9. Ship ◄────┤◄─────────────┤ + │ │ │ +``` + +## Anti-Patterns + +- **No spec**: Never start implementation without a spec. Even a 3-line spec is better than none. +- **Giant commits**: Break work into small, reviewable pieces. +- **Skipping gates**: All blocking gates must pass. No exceptions. +- **Gold plating**: Do what the spec says. Nothing more, nothing less. diff --git a/legacy/README.md b/legacy/README.md new file mode 100644 index 0000000..5b98eb2 --- /dev/null +++ b/legacy/README.md @@ -0,0 +1,26 @@ +# Legacy Infrastructure (2016-2019) + +This directory contains the original buildmachine Docker Compose CI/CD environment, archived for reference. + +## Components + +- **Jenkins** (Blue Ocean) — CI/CD server +- **Nexus 2** — artifact repository +- **SonarQube** — code quality analysis +- **Selenium Hub** — browser-based testing (Firefox + Chrome nodes) +- **PostgreSQL** — SonarQube database +- **Backup container** — volume backup utility + +## Usage + +These scripts are no longer actively maintained. If you need to run the legacy stack: + +```bash +cd legacy/ +source env-devel-local.sh +docker compose up -d +``` + +## Why Archived + +The images (`jenkinsci/blueocean`, `sonatype/nexus`) are deprecated. The project has evolved to use AI agents and GitHub Actions instead of on-premise CI/CD tools. diff --git a/backup.sh b/legacy/backup.sh similarity index 100% rename from backup.sh rename to legacy/backup.sh diff --git a/backup_all.sh b/legacy/backup_all.sh similarity index 100% rename from backup_all.sh rename to legacy/backup_all.sh diff --git a/backup_jenkins.sh b/legacy/backup_jenkins.sh similarity index 100% rename from backup_jenkins.sh rename to legacy/backup_jenkins.sh diff --git a/backup_nexus.sh b/legacy/backup_nexus.sh similarity index 100% rename from backup_nexus.sh rename to legacy/backup_nexus.sh diff --git a/backup_sonar.sh b/legacy/backup_sonar.sh similarity index 100% rename from backup_sonar.sh rename to legacy/backup_sonar.sh diff --git a/build.sh b/legacy/build.sh similarity index 100% rename from build.sh rename to legacy/build.sh diff --git a/connect.sh b/legacy/connect.sh similarity index 100% rename from connect.sh rename to legacy/connect.sh diff --git a/create_host_nexus_user.sh b/legacy/create_host_nexus_user.sh similarity index 100% rename from create_host_nexus_user.sh rename to legacy/create_host_nexus_user.sh diff --git a/create_volumes.sh b/legacy/create_volumes.sh similarity index 100% rename from create_volumes.sh rename to legacy/create_volumes.sh diff --git a/docker-compose.yml b/legacy/docker-compose.yml similarity index 100% rename from docker-compose.yml rename to legacy/docker-compose.yml diff --git a/env-devel-local.sh b/legacy/env-devel-local.sh similarity index 100% rename from env-devel-local.sh rename to legacy/env-devel-local.sh diff --git a/remove_volumes.sh b/legacy/remove_volumes.sh similarity index 100% rename from remove_volumes.sh rename to legacy/remove_volumes.sh diff --git a/restore_all.sh b/legacy/restore_all.sh similarity index 100% rename from restore_all.sh rename to legacy/restore_all.sh diff --git a/restore_jenkins.sh b/legacy/restore_jenkins.sh similarity index 100% rename from restore_jenkins.sh rename to legacy/restore_jenkins.sh diff --git a/restore_nexus.sh b/legacy/restore_nexus.sh similarity index 100% rename from restore_nexus.sh rename to legacy/restore_nexus.sh diff --git a/restore_sonar.sh b/legacy/restore_sonar.sh similarity index 100% rename from restore_sonar.sh rename to legacy/restore_sonar.sh diff --git a/show_initial_jenkins_password.sh b/legacy/show_initial_jenkins_password.sh similarity index 100% rename from show_initial_jenkins_password.sh rename to legacy/show_initial_jenkins_password.sh diff --git a/start.sh b/legacy/start.sh similarity index 100% rename from start.sh rename to legacy/start.sh diff --git a/stop.sh b/legacy/stop.sh similarity index 100% rename from stop.sh rename to legacy/stop.sh diff --git a/quality/gates.md b/quality/gates.md new file mode 100644 index 0000000..6b527f7 --- /dev/null +++ b/quality/gates.md @@ -0,0 +1,45 @@ +# Quality Gates + +## Gate Definitions + +### 1. Lint (Blocking) +- **Shell scripts**: [ShellCheck](https://www.shellcheck.net/) with default rules +- **Markdown**: [markdownlint](https://github.com/DavidAnson/markdownlint) with default rules +- **YAML**: yamllint (when applicable) + +### 2. Build (Blocking) +- `docker compose build` succeeds for any Docker-based components +- No build warnings treated as errors + +### 3. Test (Blocking) +- All existing tests pass +- New code has corresponding tests +- No decrease in coverage + +### 4. Security (Blocking) +- CodeQL reports no new high/critical alerts +- `gh-advisory-database` check passes for new dependencies +- No secrets committed (checked by secret scanning) + +### 5. AI Code Review (Advisory) +- Claude `code_review` or CodeRabbit runs on every PR +- Feedback is addressed or explicitly dismissed with rationale + +## How to Run Gates Locally + +```bash +# Shell lint +shellcheck legacy/*.sh + +# Markdown lint +npx markdownlint-cli2 "**/*.md" + +# Security — check a dependency +# (done automatically in CI) +``` + +## Adding New Gates + +1. Define the gate in this file +2. Add the corresponding step in `.github/workflows/ci.yml` +3. Update `CLAUDE.md` quality gates table diff --git a/specs/0001-setup-ci.md b/specs/0001-setup-ci.md new file mode 100644 index 0000000..3a343b4 --- /dev/null +++ b/specs/0001-setup-ci.md @@ -0,0 +1,25 @@ +# 0001 — Setup CI with GitHub Actions + +## Goal +Create a basic GitHub Actions CI workflow that enforces quality gates on every PR. + +## Context +This is the first task for the AI-driven buildmachine. We need CI before anything else — it's the foundation that ensures all subsequent work meets quality standards. + +## Constraints +- Must work with the current repo structure (shell scripts, markdown, YAML) +- Must not require paid GitHub features +- Must complete in under 5 minutes + +## Acceptance Criteria +- [ ] ShellCheck runs on all `.sh` files +- [ ] Markdown lint runs on all `.md` files +- [ ] CI triggers on PRs to `main` +- [ ] CI triggers on pushes to `main` +- [ ] Failed gates block the PR + +## Examples +A PR that introduces a shell script with `echo $UNQUOTED_VAR` should fail the ShellCheck gate. + +## Notes +This spec was the first task processed through the 9-phase workflow. diff --git a/specs/README.md b/specs/README.md new file mode 100644 index 0000000..2c8c12c --- /dev/null +++ b/specs/README.md @@ -0,0 +1,17 @@ +# Task Specifications + +This directory contains task specifications for AI agents. + +Each file describes a single task using the template defined in `CLAUDE.md`. + +## Naming Convention + +``` +NNNN-short-description.md +``` + +Where `NNNN` is a zero-padded sequential number (e.g., `0001-setup-ci.md`). + +## Template + +See the "How to Write a Good Spec" section in `/CLAUDE.md`.