diff --git a/README.md b/README.md index cffc733..871b63e 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,6 @@ Platform: linux/amd64. [channel](channels/email/package.yaml), [forge](forge/gitea/package.yaml), [secret engine](secret-engines/bws/package.yaml), [playbook](playbooks/bug-tdd/package.yaml), - [profile](profiles/network-investigator/package.yaml), - [skill](skills/archie-wf-go-gate/SKILL.md) + [profile](profiles/network-investigator/package.yaml) - Pack one package or publish the signed catalogue: [scripts/pack.sh](scripts/pack.sh), [scripts/publish.sh](scripts/publish.sh) diff --git a/skills/archie-wf-frontend/SKILL.md b/skills/archie-wf-frontend/SKILL.md deleted file mode 100644 index 31c328c..0000000 --- a/skills/archie-wf-frontend/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: archie-wf-frontend -description: > - Runs frontend quality checks: stylelint for CSS, htmlhint for HTML. - Gate stage runs these after Go vet/build/test. Use in any project - with web assets to catch syntax errors, broken selectors, and - structural issues before they reach a PR. -version: 1.1.0 -metadata: - archie: - workflow: frontend - tools: [stylelint, htmlhint] - engine: any ---- - -# Frontend Quality Gate - -## When this runs - -This skill adds frontend linting to the gate stage. After Go checks pass, -the gate runs: - -1. `stylelint "**/*.css"` -- catches syntax errors, invalid properties, - duplicate selectors, calc() misuse, missing units -2. `htmlhint "**/*.html"` -- catches unclosed tags, mismatched pairs, - duplicate IDs, inline style abuse, missing viewport meta - -Both must exit 0. If either fails, the stage parks with the lint output. - -## How to use in your project - -1. Copy this skill directory into your skills directory -2. Add to your daemon config gate: - ```toml - gate = [ - ["go", "vet", "./..."], - ["go", "test", "./..."], - ["stylelint", "**/*.css"], - ["htmlhint", "**/*.html"], - ] - ``` -3. Or declare `workflow: frontend` in the skill frontmatter -- archie-core - loads the skill body and the agent knows to run these during build diff --git a/skills/archie-wf-frontend/package.yaml b/skills/archie-wf-frontend/package.yaml deleted file mode 100644 index fb6f49e..0000000 --- a/skills/archie-wf-frontend/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-frontend -description: "Runs frontend quality checks: stylelint for CSS, htmlhint for HTML. Gate stage runs these after Go vet/build/test. Use in any project with web assets to catch syntax errors, broken selectors, and structural issues before they reach a PR." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420 diff --git a/skills/archie-wf-go-gate/SKILL.md b/skills/archie-wf-go-gate/SKILL.md deleted file mode 100644 index 00a25d8..0000000 --- a/skills/archie-wf-go-gate/SKILL.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -name: go-quality-gate -description: > - Run the full Go quality pipeline: gofumpt, go fix, golangci-lint, go test -race, - and task deadcode. Use before any commit in a Go project. Triggered automatically - by archie-core's implement and tdd workflows via the per-repo gate config. -version: 1.0.0 -metadata: - archie: - tools: [go, golangci-lint, gofumpt, task] - engine: any ---- - -# Go Quality Gate - -## When this runs - -arcie-core enforces this gate after every builder agent stage. The specific commands -come from the repository's `[[repos.gate]]` config, not this skill. This skill documents -what a correct gate looks like and how to diagnose failures. - -## Standard gate - -Run in this exact order. archie-core does NOT run these -- the `ai-sdk/agentloop` gate -does. This list is what you should configure in `config.toml`: - -```toml -[[repos.gate]] = ["gofumpt", "-w", "."] -[[repos.gate]] = ["go", "fix", "./..."] -[[repos.gate]] = ["golangci-lint", "run", "./..."] -[[repos.gate]] = ["go", "test", "-race", "-count=1", "./..."] -``` - -Or if the project uses Task: - -```toml -[[repos.gate]] = ["task", "check"] -``` - -The LAST command in the gate list is the test runner by convention. archie-core's -TDD workflow inverts only that last command during the repro stage. - -## Diagnosing gate failures - -### gofumpt / go fix - -These mutate files. If they change anything, the next `git diff` will catch it. -The agent should re-run them after making changes. - -### golangci-lint - -Common failures and fixes: - -- `unused` -- remove the unused function or add `//nolint:unused` -- `errcheck` -- handle the error or assign to `_` -- `gosec` -- review the security finding; never blindly suppress - -### go test -race - -Data races are non-deterministic. If `-race` fails: - -1. Identify the race with `go test -race -run=TestName` -2. Add a mutex or channel to protect the shared state -3. Re-run with `-count=5` to confirm it's gone - -### task deadcode - -Scoping rule: if deadcode fails on packages you didn't touch, scope it: - -```bash -golangci-lint run --tests=false --enable-only=unused,staticcheck ./changed/pkg/... -``` - -## When the TDD workflow runs - -During `repro-tests`, the test command's expectations are INVERTED -- it must FAIL. -During `fix`, the full gate runs normally and test files are write-protected. -The agent cannot modify tests in the fix stage; it must fix the code to make them pass. diff --git a/skills/archie-wf-go-gate/package.yaml b/skills/archie-wf-go-gate/package.yaml deleted file mode 100644 index 9e82822..0000000 --- a/skills/archie-wf-go-gate/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-go-gate -description: "Run the full Go quality pipeline: gofumpt, go fix, golangci-lint, go test -race, and task deadcode. Use before any commit in a Go project. Triggered automatically by archie-core's implement and tdd workflows via the per-repo gate config." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420 diff --git a/skills/archie-wf-node/SKILL.md b/skills/archie-wf-node/SKILL.md deleted file mode 100644 index 86de947..0000000 --- a/skills/archie-wf-node/SKILL.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -name: ecosystem-node -description: > - Node.js/TypeScript project conventions for archie-core: npm/pnpm, eslint, - prettier, tsc, vitest. Use when working on Node repositories with archie-core. -version: 1.0.0 -metadata: - archie: - tools: [node, npm, pnpm, vitest, eslint, prettier] - engine: any ---- - -# Node.js / TypeScript Ecosystem Conventions - -## Preflight - -When archie-core's `[[repos]]` entry sets `ecosystem = "node"`, the daemon runs -`node --version` as the preflight check before any agent stage. - -## Recommended gate configuration - -```toml -[[repos]] -owner = "acme" -name = "my-node-project" -ecosystem = "node" - -[[repos.gate]] = ["pnpm", "run", "lint"] -[[repos.gate]] = ["pnpm", "run", "typecheck"] -[[repos.gate]] = ["pnpm", "run", "test"] -``` - -Or for npm projects: - -```toml -[[repos.gate]] = ["npm", "run", "lint"] -[[repos.gate]] = ["npm", "run", "build", "--", "--noEmit"] -[[repos.gate]] = ["npm", "test"] -``` - -## Test glob - -The default test glob for Node is `*.test.ts`. The TDD workflow's repro-tests -stage write-protects files matching this glob during the fix stage. - -Override with `test_glob = "**/*.spec.ts"` for projects using that convention, -or `test_glob = "__tests__/**/*.ts"` for Jest-style test directories. - -## Package management - -arcie-core detects the lockfile: - -- `pnpm-lock.yaml` → use `pnpm` -- `package-lock.json` → use `npm` -- `yarn.lock` → use `yarn` - -Install before gate: - -```bash -pnpm install --frozen-lockfile -``` - -## Common tools - -| Tool | Purpose | Config file | -| -------------- | ---------------- | ------------------- | -| `eslint` | Linting | `eslint.config.mjs` | -| `prettier` | Formatting | `.prettierrc` | -| `tsc --noEmit` | Type checking | `tsconfig.json` | -| `vitest` | Testing | `vitest.config.ts` | -| `jest` | Testing (legacy) | `jest.config.ts` | - -## Common gate failures - -### eslint - -- `no-unused-vars`: remove unused import/variable -- `@typescript-eslint/no-explicit-any`: add proper type -- Import order: let eslint fix it with `--fix` - -### tsc / typecheck - -- `TS2345`: type mismatch -- fix the argument or the signature -- `TS2339`: property doesn't exist -- check the type definition -- `Cannot find module`: check the import path or install the package - -### vitest / jest - -- Test timeout: the test is hanging -- check async/await, mocks, or network calls -- Snapshot mismatch: the output changed -- update the snapshot if the change is intentional -- Assertion failure: fix the code, not the test diff --git a/skills/archie-wf-node/package.yaml b/skills/archie-wf-node/package.yaml deleted file mode 100644 index fb1444b..0000000 --- a/skills/archie-wf-node/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-node -description: "Node.js/TypeScript project conventions for archie-core: npm/pnpm, eslint, prettier, tsc, vitest. Use when working on Node repositories with archie-core." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420 diff --git a/skills/archie-wf-python/SKILL.md b/skills/archie-wf-python/SKILL.md deleted file mode 100644 index 3fcb2d8..0000000 --- a/skills/archie-wf-python/SKILL.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: ecosystem-python -description: > - Python project conventions for archie-core: venv, pytest, ruff, mypy, pip-audit. - Use when working on Python repositories with archie-core. -version: 1.0.0 -metadata: - archie: - tools: [python, pytest, ruff, mypy, pip-audit] - engine: any ---- - -# Python Ecosystem Conventions - -## Preflight - -When archie-core's `[[repos]]` entry sets `ecosystem = "python"`, the daemon runs -`python --version` as the preflight check before any agent stage. - -## Recommended gate configuration - -```toml -[[repos]] -owner = "acme" -name = "my-python-project" -ecosystem = "python" - -[[repos.gate]] = ["ruff", "check", "."] -[[repos.gate]] = ["ruff", "format", "--check", "."] -[[repos.gate]] = ["mypy", "."] -[[repos.gate]] = ["pytest", "-x", "--tb=short"] -``` - -## Test glob - -The default test glob for Python is `test_*.py`. The TDD workflow's repro-tests -stage write-protects files matching this glob during the fix stage. - -Override with `test_glob = "tests/**/*.py"` in the repo config for projects -with test files outside the package root. - -## Package management - -arcie-core assumes: - -- `requirements.txt` or `pyproject.toml` at the repo root -- Tests run with `pytest` (the ecosystem default) -- Linting with `ruff` (recommended) or `flake8` -- Type checking with `mypy` -- Security auditing with `pip-audit` - -## Virtual environment - -Before the gate runs, ensure dependencies are installed: - -```bash -python -m venv .venv -. .venv/bin/activate -pip install -r requirements.txt -pip install pytest ruff mypy pip-audit -``` - -For `pyproject.toml` projects: - -```bash -pip install -e ".[dev]" -``` - -## Common gate failures - -### ruff - -- `F401`: unused import -- remove it -- `E501`: line too long -- break the line -- `I001`: import order -- let ruff fix it with `ruff check --fix` - -### mypy - -- Missing type annotation on public function -- add it -- `Cannot determine type` -- add explicit annotation -- Import errors -- check the package is installed in the venv - -### pytest - -- Test discovery failed -- check `__init__.py` files and test naming -- Import errors -- verify the package is installed (`pip install -e .`) -- Assertion failures -- fix the code, not the test diff --git a/skills/archie-wf-python/package.yaml b/skills/archie-wf-python/package.yaml deleted file mode 100644 index 0ea3cf8..0000000 --- a/skills/archie-wf-python/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-python -description: "Python project conventions for archie-core: venv, pytest, ruff, mypy, pip-audit. Use when working on Python repositories with archie-core." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420 diff --git a/skills/archie-wf-security/SKILL.md b/skills/archie-wf-security/SKILL.md deleted file mode 100644 index af992bd..0000000 --- a/skills/archie-wf-security/SKILL.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -name: security-audit -description: > - Scan code for security vulnerabilities: hardcoded secrets, injection vectors, - unsafe deserialization, missing auth checks, and path traversal. Use on PRs - touching auth, API endpoints, or data handling code. -version: 1.0.0 -metadata: - archie: - tools: [golangci-lint, trivy, gitleaks] - engine: any ---- - -# Security Audit - -## When to use - -Run this audit when: - -- A PR touches authentication, authorisation, or session code -- New API endpoints are added -- Database queries or file I/O paths change -- The issue mentions "security", "vulnerability", "CVE", or "auth" -- A dependency update changes major versions - -## What to check - -### 1. Hardcoded secrets - -Scan for: - -- API keys, tokens, passwords in source files -- `.env` files committed to the repo -- Credentials in test fixtures - -Use `gitleaks detect --no-git` for a fast scan. - -### 2. Injection vectors - -- **SQL:** any string concatenation in query building. Use parameterised queries. -- **Command:** any `os/exec` with user-controlled input. Use `exec.Command` with separate args, never `sh -c`. -- **Path:** any file path constructed from user input without validation. Use `filepath.Clean` and check the resolved path is within the expected directory. - -### 3. Unsafe deserialization - -- `json.Unmarshal` on untrusted input into `interface{}` or `map[string]any` without validation -- `yaml.Unmarshal` without `KnownFields` or strict mode -- `gob.Decode` on network input - -### 4. Missing auth checks - -- New endpoints without middleware -- Internal/admin endpoints exposed without auth -- Token validation that only checks signature, not expiry or revocation - -### 5. Dependency CVEs - -Run `trivy fs --severity HIGH,CRITICAL .` on the repository. -Report each finding with: - -- Package name and version -- CVE ID -- CVSS score -- Fixed version (if available) - -## Reporting - -For each finding, report: - -1. **Severity:** Critical / High / Medium / Low -2. **Location:** file, line, function -3. **Description:** what's wrong -4. **Fix:** specific code change needed -5. **Prevention:** how to catch this in future (lint rule, gate addition) - -If nothing is found, report clean. Never fabricate findings. diff --git a/skills/archie-wf-security/package.yaml b/skills/archie-wf-security/package.yaml deleted file mode 100644 index 0ab5304..0000000 --- a/skills/archie-wf-security/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-security -description: "Scan code for security vulnerabilities: hardcoded secrets, injection vectors, unsafe deserialization, missing auth checks, and path traversal. Use on PRs touching auth, API endpoints, or data handling code." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420 diff --git a/skills/archie-wf-tdd/SKILL.md b/skills/archie-wf-tdd/SKILL.md deleted file mode 100644 index 37d1543..0000000 --- a/skills/archie-wf-tdd/SKILL.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: archie-wf-tdd -description: > - Fix bugs using test-driven development. Write a failing repro test first, prove - it captures the bug, then fix the code without touching the tests. archie-core - routes issues labelled "bug" through this workflow automatically. -version: 1.0.0 -metadata: - archie: - tools: [go, golangci-lint] - engine: any - workflow: tdd ---- - -# TDD Bugfix Workflow - -## When this runs - -arcie-core routes any GitHub issue labelled `bug` through the TDD workflow. -The workflow has five stages: analyse → repro-tests → capture-proof → fix → deliver. - -## Stage 1: Analyse (read-only planner) - -The planner agent explores the codebase read-only and produces: - -- Root cause: the exact file, function, and condition -- The expected vs actual behaviour -- Which test cases would prove the bug exists - -No code is written. The plan is stored but not posted -- the repro proof speaks louder. - -## Stage 2: Repro Tests (write failing tests only) - -The agent writes tests that PROVE the bug. Critical constraints: - -- **Do not touch non-test files.** Only `*_test.go` (or the ecosystem's test glob). -- **The gate is inverted.** The test command (last in `[[repos.gate]]`) must FAIL. - If it passes, the repro didn't capture the bug and the stage parks. -- **Make the failure explicit.** The test should assert the correct behaviour, - not just `panic()` or `t.FailNow()`. - -## Stage 3: Capture Proof (deterministic) - -arcie-core runs the test command directly (not through the agent loop) and captures -the output. This is deterministic proof that the tests fail before the fix. - -## Stage 4: Fix (code only) - -The agent fixes the bug. Critical constraints: - -- **Test files are write-protected.** The agent CANNOT modify `*_test.go`. - This is an environmental constraint, not a prompt rule. -- **The full gate runs normally.** All quality commands plus the test suite must pass. -- **Make the smallest fix.** Change only what's needed to make the repro tests pass. - -## Stage 5: Deliver - -arcie-core: - -1. Commits both the repro and the fix as separate commits (telling the PR story) -2. Pushes the branch -3. Opens a PR with the builder's summary -4. Posts the captured failure proof as a PR comment - -## Common pitfalls - -### The repro tests pass unexpectedly - -This means the test doesn't actually capture the bug. Check: - -- Is the test calling the right function with the right inputs? -- Is the assertion checking the correct behaviour (not the buggy behaviour)? -- Are there test setup issues (missing imports, wrong package)? - -### The fix stage modifies test files - -This shouldn't happen -- test files are write-protected. If it does, the agent is -bypassing the constraint. The worktree should be inspected. - -### The gate is misconfigured - -If the repo has no `[[repos.gate]]` entries, TDD cannot run -- it needs at least -one gate command, with the test runner last. diff --git a/skills/archie-wf-tdd/package.yaml b/skills/archie-wf-tdd/package.yaml deleted file mode 100644 index e43ad46..0000000 --- a/skills/archie-wf-tdd/package.yaml +++ /dev/null @@ -1,10 +0,0 @@ -apiVersion: dev.archie.package.v1 -displayName: archie-wf-tdd -description: "Fix bugs using test-driven development. Write a failing repro test first, prove it captures the bug, then fix the code without touching the tests. archie-core routes issues labelled \"bug\" through this workflow automatically." -version: 1.0.0 -contributes: - skills: - - SKILL.md -files: - - path: SKILL.md - mode: 420