From b7c821ea7accc54570e340607fbc75d163248744 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Sun, 4 Oct 2026 17:08:50 +1100 Subject: [PATCH] feat(skills): the archie-wf skills as packages --- README.md | 1 + skills/archie-wf-frontend/SKILL.md | 43 ++++++++++++ skills/archie-wf-frontend/package.yaml | 10 +++ skills/archie-wf-go-gate/SKILL.md | 78 ++++++++++++++++++++++ skills/archie-wf-go-gate/package.yaml | 10 +++ skills/archie-wf-node/SKILL.md | 91 ++++++++++++++++++++++++++ skills/archie-wf-node/package.yaml | 10 +++ skills/archie-wf-python/SKILL.md | 87 ++++++++++++++++++++++++ skills/archie-wf-python/package.yaml | 10 +++ skills/archie-wf-security/SKILL.md | 76 +++++++++++++++++++++ skills/archie-wf-security/package.yaml | 10 +++ skills/archie-wf-tdd/SKILL.md | 83 +++++++++++++++++++++++ skills/archie-wf-tdd/package.yaml | 10 +++ 13 files changed, 519 insertions(+) create mode 100644 skills/archie-wf-frontend/SKILL.md create mode 100644 skills/archie-wf-frontend/package.yaml create mode 100644 skills/archie-wf-go-gate/SKILL.md create mode 100644 skills/archie-wf-go-gate/package.yaml create mode 100644 skills/archie-wf-node/SKILL.md create mode 100644 skills/archie-wf-node/package.yaml create mode 100644 skills/archie-wf-python/SKILL.md create mode 100644 skills/archie-wf-python/package.yaml create mode 100644 skills/archie-wf-security/SKILL.md create mode 100644 skills/archie-wf-security/package.yaml create mode 100644 skills/archie-wf-tdd/SKILL.md create mode 100644 skills/archie-wf-tdd/package.yaml diff --git a/README.md b/README.md index c604b28..6f821e4 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ directory holds one subdirectory per extension. ``` secret-engines// package.yaml + Go source, served over secretengine.v1 +skills// package.yaml + SKILL.md, projected into skills workflows// package.yaml + workflow YAML, projected into workflow-definitions channels// package.yaml + Go source, served over channel.v1 (webhook, email) forge// package.yaml + Go source, served over forge.v1 (github, gitea) diff --git a/skills/archie-wf-frontend/SKILL.md b/skills/archie-wf-frontend/SKILL.md new file mode 100644 index 0000000..31c328c --- /dev/null +++ b/skills/archie-wf-frontend/SKILL.md @@ -0,0 +1,43 @@ +--- +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 new file mode 100644 index 0000000..fb6f49e --- /dev/null +++ b/skills/archie-wf-frontend/package.yaml @@ -0,0 +1,10 @@ +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 new file mode 100644 index 0000000..00a25d8 --- /dev/null +++ b/skills/archie-wf-go-gate/SKILL.md @@ -0,0 +1,78 @@ +--- +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 new file mode 100644 index 0000000..9e82822 --- /dev/null +++ b/skills/archie-wf-go-gate/package.yaml @@ -0,0 +1,10 @@ +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 new file mode 100644 index 0000000..86de947 --- /dev/null +++ b/skills/archie-wf-node/SKILL.md @@ -0,0 +1,91 @@ +--- +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 new file mode 100644 index 0000000..fb1444b --- /dev/null +++ b/skills/archie-wf-node/package.yaml @@ -0,0 +1,10 @@ +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 new file mode 100644 index 0000000..3fcb2d8 --- /dev/null +++ b/skills/archie-wf-python/SKILL.md @@ -0,0 +1,87 @@ +--- +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 new file mode 100644 index 0000000..0ea3cf8 --- /dev/null +++ b/skills/archie-wf-python/package.yaml @@ -0,0 +1,10 @@ +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 new file mode 100644 index 0000000..af992bd --- /dev/null +++ b/skills/archie-wf-security/SKILL.md @@ -0,0 +1,76 @@ +--- +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 new file mode 100644 index 0000000..0ab5304 --- /dev/null +++ b/skills/archie-wf-security/package.yaml @@ -0,0 +1,10 @@ +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 new file mode 100644 index 0000000..37d1543 --- /dev/null +++ b/skills/archie-wf-tdd/SKILL.md @@ -0,0 +1,83 @@ +--- +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 new file mode 100644 index 0000000..e43ad46 --- /dev/null +++ b/skills/archie-wf-tdd/package.yaml @@ -0,0 +1,10 @@ +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