Transform buildmachine into AI-driven software house foundation

.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'

.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/

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/<name>` — feature work
+- `fix/<name>` — bug fixes
+- `chore/<name>` — 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.