From a7f19b254b8107960524f916fb184829c293958b Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 7 May 2026 17:24:09 -0400 Subject: [PATCH 1/2] Trim AGENTS.md from 369 to 122 lines The wg-agentic-sdlc repo-scaffolding best practices recommend AGENTS.md files stay under 150 lines, citing ETH Zurich research showing agent adherence drops with context file length. The prior AGENTS.md was 369 lines, with most content duplicating what each workflow's guidelines.md and skills/*.md already provide in the AI execution chain. Removed sections verified as duplicated: - Workflow-Specific Notes (covered in each workflow's guidelines.md) - Prerequisites per workflow (in each workflow's guidelines.md/skills) - Artifact Management per-workflow listing (in each workflow's docs) - Common Commands (generic tooling agents already know) - Verbose Shared Resources explanation (files are self-documenting) Relocated unique content: - Claude Code installation internals moved to CONTRIBUTING.md Added: - One-sentence recipe concept explanation after the _shared/ tree - Alphabetized workflow list - README.md annotation noting it contains prerequisites and artifacts Validated by running a fresh-session test confirming an agent with only the trimmed AGENTS.md could navigate the repo, understand the recipe system, identify relevant workflows, and follow path conventions. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 292 ++++-------------------------------------------- CONTRIBUTING.md | 11 ++ 2 files changed, 34 insertions(+), 269 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9e1671..ef8c2b7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,16 +9,16 @@ This repository contains reusable AI coding workflows that can be installed glob **Current workflows:** - **ai-ready** — Codebase scanning and AGENTS.md generation (update) - **bugfix** — Systematic bug resolution (assess, reproduce, diagnose, fix, test, review, document, pr) -- **docs-writer** — Documentation creation workflow -- **triage** — Bulk Jira bug triage with AI-driven categorization and HTML reports -- **skill-reviewer** — Meta-workflow that audits AI skill directories +- **code-review** — AI-driven code review with human-in-the-loop decisions (start, continue, clean) - **cve-fix** — Automated CVE remediation from Jira tickets (start, patch, validate, pr, backport, close) -- **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond) - **design** — Design-and-decompose workflow (ingest, research, draft, decompose, revise, publish, respond, sync) -- **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond) +- **docs-writer** — Documentation creation workflow (gather, plan, draft, validate, apply, mr) - **e2e** — Story-to-tests workflow for [QE] stories (ingest, plan, revise, code, validate, publish, respond) -- **code-review** — AI-driven code review with human-in-the-loop decisions (start, continue, clean) +- **implement** — Story-to-code workflow (ingest, plan, revise, code, validate, publish, respond) - **kcs** — KCS Solution article workflow (gather, draft, validate, handoff) +- **prd** — Requirements-to-PRD workflow (ingest, clarify, draft, revise, publish, respond) +- **skill-reviewer** — Meta-workflow that audits AI skill directories +- **triage** — Bulk Jira bug triage with AI-driven categorization and HTML reports ## Architecture @@ -30,7 +30,7 @@ Every workflow follows this canonical structure: workflow-name/ SKILL.md # Entry point with YAML frontmatter (name, description) guidelines.md # Behavioral rules: principles, hard limits, safety, quality - README.md # Human-readable documentation + README.md # Human-readable documentation (prerequisites, artifacts, usage) skills/ controller.md # Optional phase dispatcher phase-name.md # Implementation for each phase @@ -45,39 +45,18 @@ workflow-name/ 2. **Progressive disclosure**: SKILL.md is thin (under 30 lines), details live in guidelines.md and skills/ 3. **Relative paths**: All file references must be relative to the file's location (for symlink compatibility) 4. **Phase-based execution**: Most workflows operate through discrete phases with explicit transitions -5. **Shared resources**: Cross-cutting concerns live in `_shared/` and are referenced by relative path from workflow skills +5. **Shared resources**: Cross-cutting concerns live in `_shared/` and are referenced by relative path ### Shared Resources (`_shared/`) -Cross-cutting concerns that multiple workflows need are extracted into -`_shared/` to avoid duplication and ensure consistency: - ```text _shared/ - review-protocol.md # Evaluation criteria, finding format, severity definitions + review-protocol.md # Shared code review criteria, finding format, severity definitions recipes/ - self-review-gate.md # Self-review quality gate for pre-PR code review + self-review-gate.md # Pre-PR self-review quality gate (used by bugfix, implement, e2e, cve-fix) ``` -**Review protocol** (`review-protocol.md`): Defines the shared evaluation -criteria (correctness, error handling, security, performance, naming, test -coverage, conventions), finding format, severity definitions, and validation -rules used by the standalone `code-review` workflow and the self-review gates -embedded in all code-changing workflows. - -**Recipes** (`recipes/`): Self-contained, parameterized procedures that -workflows reference at specific points. Each recipe has a Parameters section -defining what the calling skill must provide, followed by the complete -procedure. Recipes are referenced via relative path from the calling skill -(e.g., `../../_shared/recipes/self-review-gate.md` from `workflow/skills/`). - -**Self-review gate** (`recipes/self-review-gate.md`): A quality gate that -reviews code changes before they are pushed or submitted as a PR. Discovers -the project's preferred non-interactive review tool from AGENTS.md/CLAUDE.md; -if none is specified, performs a structured self-review using the shared review -protocol. Strongest at catching mechanical issues (convention violations, -obvious bugs, inconsistencies); not a substitute for independent review. -Used by bugfix `/pr`, implement `/publish`, e2e `/publish`, and cve-fix `/pr`. +Recipes are self-contained, parameterized procedures that workflows reference via relative path (e.g., `../../_shared/recipes/self-review-gate.md` from `skills/`). ### File Reference Conventions @@ -86,248 +65,23 @@ Critical for symlink resolution: - `skills/controller.md` (when present) references sibling skills as `phase-name.md` (not `skills/phase-name.md`) - `SKILL.md` references `guidelines.md` and optionally `skills/controller.md` (same directory) -### Artifact Management - -Workflows write outputs to `.artifacts/{workflow-name}/{context}/`: -- **ai-ready**: No persistent artifacts (writes directly to the target project's AGENTS.md) -- **bugfix**: `.artifacts/bugfix/{issue-number}/` (root-cause.md, reproduction.md, etc.) -- **code-review**: `.artifacts/code-review/{branch}/` (00-reviewer-profile.md, 01-change-summary.md, code-review-{NNN}.md, review-response-{NNN}.md, review-metadata.json, decisions-{NNN}.json) -- **triage**: `.artifacts/triage/{project}/` (issues.json, analyzed.json, report.html) -- **skill-reviewer**: `.artifacts/skill-reviewer/{skill-name}/` (file-hashes.json, skill-map.md, review.md) -- **cve-fix**: `.artifacts/cve-fix/{context}/` (context.md, patch-log.md, validation-results.md, pr-description.md, backport-log.md, close-report.md) -- **prd**: `.artifacts/prd/{issue-number}/` (01-requirements.md, 02-clarifications.md, 03-prd.md, 04-pr-description.md, 05-review-responses.md) -- **design**: `.artifacts/design/{issue-number}/` (01-context.md, 02-research.md, 03-design.md, 04-epics.md, 05-stories/epic-{N}-{slug}.md, 05-stories/epic-{N}/story-{NN}-{slug}.md, 06-coverage.md, 07-pr-description.md, 08-review-responses.md, publish-metadata.json, sync-manifest.json) -- **implement**: `.artifacts/implement/{jira-key}/` (01-context.md, 02-plan.md, 03-test-report.md, 04-impl-report.md, 05-validation-report.md, 06-pr-description.md, 07-review-responses.md, publish-metadata.json) -- **e2e**: `.artifacts/e2e/{jira-key}/` (01-context.md, 02-plan.md, 03-test-report.md, 04-impl-report.md, 05-validation-report.md, 06-pr-description.md, 07-review-responses.md, publish-metadata.json) -- **kcs**: `.artifacts/kcs/{issue-key}/` (01-context.md, 02-kcs-draft.md, 03-handoff-message.md) - -## Prerequisites - -### Required for All Workflows -- Git (for version control operations) - -### Workflow-Specific Dependencies -- **ai-ready**: None (reads codebase, writes AGENTS.md) -- **bugfix**: GitHub CLI (`gh`) — for PR queries and creation -- **code-review**: None (operates on local uncommitted changes; optionally uses project's lint/test commands if discoverable) -- **triage**: Jira MCP server — configured and authenticated for Jira API access -- **docs-writer**: GitLab CLI — for merge request creation (or GitHub CLI for GitHub-hosted projects) -- **cve-fix**: Jira MCP server or Jira CLI (`jira`), GitHub CLI (`gh`), optionally `skopeo` for container image verification -- **prd**: Jira MCP server — for requirements ingestion; GitHub CLI (`gh`) — for PR creation and review comment management -- **design**: Jira MCP server or CLI — for `/ingest` (read-only) and `/sync` (creates epics/stories); GitHub CLI (`gh`) — for `/publish` and `/respond`; web search and URL fetching — for `/research` (conditional) -- **implement**: Jira MCP server or CLI — for `/ingest` (read-only); GitHub CLI (`gh`) — for `/publish` and `/respond`; project build/test/lint tooling (discovered during `/ingest`); docs repo (local clone) — for `/ingest` (reads PRD and design document) -- **e2e**: Jira MCP server or CLI — for `/ingest` (read-only); GitHub CLI (`gh`) — for `/publish` and `/respond`; project e2e test tooling (discovered during `/ingest`); docs repo (local clone) — for `/ingest` (reads PRD and design document) -- **kcs**: Jira MCP server — for `/gather` (read-only) - -## Installation System - -### install.sh - -The installer uses auto-discovery to find all workflows and creates symlinks: - -```bash -# User-level (all workflows) -./install.sh cursor # ~/.cursor/skills/ -./install.sh claude # ~/.claude/CLAUDE.md and ~/.claude/skills/ -./install.sh gemini # ~/.gemini/skills/ -./install.sh all # All environments - -# Selective workflows -./install.sh cursor --workflows bugfix,triage - -# Project-level -./install.sh cursor --project /path/to/proj # .cursor/skills/ -./install.sh claude --project /path/to/proj # .claude/CLAUDE.md and .claude/skills/ -``` - -**Auto-discovery mechanism**: The script scans for `*/SKILL.md` files at repo root. No script changes needed when adding workflows. - -### uninstall.sh - -Mirrors install.sh structure with removal logic. - -### Claude Code Integration - -For Claude Code, the installer: -1. Appends workflow references to `CLAUDE.md` (or `.claude/CLAUDE.md` for project-level) beneath the `# ai-workflows` marker -2. Symlinks workflows into `~/.claude/skills/` (or `.claude/skills/` for project-level) for slash command discovery -3. Removes stale references (old controller.md paths) to avoid duplicates - -## Development Workflows - -For detailed workflow development guidelines (structure, file conventions, testing), see CONTRIBUTING.md. - -**Quick reference:** -- New workflow: Create directory with SKILL.md, run `./install.sh --list` to verify auto-discovery -- Modify workflow: Maintain relative paths, use progressive disclosure, run skill-reviewer for validation -- Test: `./install.sh cursor && ./uninstall.sh` for clean reinstall verification - -## Workflow-Specific Notes - -### ai-ready - -- Single-phase workflow: `/update` scans the codebase and writes AGENTS.md -- No external dependencies or artifacts -- Safe for any project — reads only, writes one file - -### bugfix - -- `/pr` includes a self-review gate (`_shared/recipes/self-review-gate.md`) that reviews uncommitted changes before committing — discovers the project's review tool or falls back to the shared review protocol -- Unattended mode available: `skills/unattended.md` (chains diagnose → fix → test → review) -- Uses git commands extensively (blame, log, status, diff) -- Creates regression tests during `/test` phase -- Integrates with GitHub CLI for PR creation - -### code-review - -- Review evaluation criteria are defined in `_shared/review-protocol.md` (shared with the self-review gates in other workflows) -- No external dependencies — operates entirely on local uncommitted changes -- Discovery-based: reads AGENTS.md, CLAUDE.md, linting configs, CI workflows to build a reviewer profile automatically -- Human-in-the-loop by default: every finding is presented for user decision before any code changes -- Unattended mode available (`--unattended`): auto-implements, iterates until approved, presents summary at end -- The implementor independently assesses each reviewer finding and may disagree -- Supports optional focus guidance (e.g., `/start focus on error handling`) -- When subagents are available, the reviewer runs in a separate context for independence; when not, uses sequential review with file-based handoff -- Automatic cleanup on approval — no manual `/clean` needed for completed reviews -- `/clean` exists only for abandoned reviews that were started but never finished - -### triage - -- Requires Jira MCP server configured and authenticated -- Generates self-contained HTML reports with Material Design styling -- Read-only: never modifies Jira issues -- `/assess` is for single-issue triage (not part of bulk pipeline) -- Recently resolved bugs fetched for regression matching - -### skill-reviewer - -- Single-phase workflow (no controller) -- Read-only review (fixing findings is separate from review phase) -- Must read all files in target skill before forming opinions -- Runs `scripts/pre-review-checks.py` for automated structural, frontmatter, reference, and sequencing checks before LLM evaluation -- For large skills (15+ files), delegates initial reading to an Explore sub-agent using `prompts/analyze-skill.md`, which produces a skill map at `.artifacts/skill-reviewer/{skill-name}/skill-map.md` - -### docs-writer - -- Converts Jira tickets or GitHub issues into AsciiDoc documentation -- Runs Vale for style compliance before applying changes -- Creates GitLab merge requests (designed for GitLab-hosted docs repos, adaptable to GitHub with gh CLI) -- Must get user approval after `/plan` phase before proceeding to `/draft` - -### cve-fix - -- `/pr` includes a self-review gate (`_shared/recipes/self-review-gate.md`) that reviews dependency changes before committing — discovers the project's review tool or falls back to the shared review protocol -- Requires Jira MCP server or CLI for ticket research -- Only `/close` writes to Jira (all other phases are read-only) -- `/backport` is optional and repeatable for multiple release branches -- Container image verification via `skopeo` is optional -- Multi-strategy patching tries fixes in ascending risk order (direct → transitive → override → major) - -### prd - -- Requires Jira MCP server for requirements ingestion (read-only — never modifies Jira) -- Uses GitHub CLI (`gh`) for PR creation and review comment management -- `/clarify` has explicit exit criteria and is re-entrant (can loop back from `/draft`) -- `/respond` requires user approval before posting any PR comments -- PRD template and section guidance live in `templates/` (not embedded in skills) -- Must get user review after `/draft` before proceeding to `/publish` - -### design - -- Requires a completed PRD (`.artifacts/prd/{issue-number}/03-prd.md`) as input -- Jira is read-only until `/sync`; only `/sync` creates issues, and only with dry-run + explicit approval -- Design and decomposition co-evolve — changes to the design flag the decomposition for regeneration, and decomposition gaps recommend revising the design -- Shares docs repo config with PRD workflow (`.artifacts/prd/config.json`) -- Design doc template and section guidance live in `templates/` with project-level override support -- Each story must include functionality AND testing (no deferred test stories) - -### implement - -- `/publish` includes a self-review gate (`_shared/recipes/self-review-gate.md`) that reviews branch changes before pushing — discovers the project's review tool or falls back to the shared review protocol -- Requires a Jira Story (typically created by the design workflow's `/sync` phase) as input -- Jira is read-only — no phase in this workflow writes to Jira -- Discovery-based validation: build, test, lint, and coverage commands are discovered during `/ingest` from the project's AGENTS.md, Makefile, and CI workflows — not hardcoded -- Contract-based testing: tests validate behavioral contracts through public interfaces; unit tests always required, integration tests required when the story touches component interactions -- Incremental commits prefixed with Jira key — no squashing, each commit independently meaningful for backporting -- Plan evolves during implementation — `02-plan.md` is updated as tasks complete, enabling resumption after interruptions -- Code changes happen in the source repo on a feature branch; `/publish` creates a PR in the source repo (not a separate docs repo) - -### e2e - -- `/publish` includes a self-review gate (`_shared/recipes/self-review-gate.md`) that reviews branch changes before pushing — discovers the project's review tool or falls back to the shared review protocol -- Requires a Jira [QE] Story (typically created by the design workflow's `/sync` phase) as input -- Jira is read-only — no phase in this workflow writes to Jira -- Discovery-based infrastructure: e2e test framework, test infrastructure abstractions (harness, fixtures, page objects, helpers — whatever the project uses), auxiliary services (if any), execution commands, and conventions are discovered during `/ingest` — not hardcoded -- Reference suite pattern: before writing tests, identifies the most similar existing e2e test suite and extracts its patterns (imports, lifecycle hooks, test infrastructure usage, assertions, labels) -- Scenario-driven planning: each acceptance criterion maps to concrete test scenarios with specific test grouping, steps, assertions, and labels -- Anti-pattern detection during `/validate`: checks for hardcoded sleeps, brittle selectors, order-dependent tests, shared mutable state, missing cleanup, test infrastructure bypass, missing labels, hardcoded values, missing async polling, missing failure diagnostics -- Feature defects are not test bugs — if tests reveal a defect in the [DEV] implementation, the test is adjusted (xfail/skip) and the defect is noted in the implementation report -- Plan evolves during implementation — `02-plan.md` is updated as tasks complete, enabling resumption after interruptions -- Code changes happen in the source repo on a feature branch; `/publish` creates a PR in the source repo - -### kcs - -- Requires Jira MCP server for `/gather` (read-only — never modifies Jira) -- Produces KCS Solution articles in markdown following the KCS Content Standard -- Article template, section guidance, and validation checklist live in `templates/` -- `/validate` checks the draft against a structured checklist and fixes violations inline -- `/handoff` composes a channel-agnostic message for the support engineer -- Must get user confirmation between phases; all `/validate` blockers must be resolved before `/handoff` - -## Common Commands - -**Note**: This repository contains AI workflow definitions (markdown files), not traditional code requiring build/test commands. "Testing" refers to verifying workflow execution and symlink installation. - -### Installation -```bash -./install.sh all # Install all workflows, all environments -./install.sh cursor --workflows bugfix # Install specific workflow -./install.sh --list # List available workflows -./uninstall.sh cursor # Remove Cursor installation - -# Verify installation -ls -la ~/.cursor/skills/ # Check Cursor symlinks -ls -la ~/.claude/skills/ # Check Claude Code symlinks -cat ~/.claude/CLAUDE.md # Verify Claude Code references -``` - -### Git Workflow -```bash -git status # Check staged changes -git diff # Review changes -git log --oneline -10 # Recent commits -git blame # Trace file history -``` - -### GitHub CLI (for bugfix) -```bash -gh pr list --state open -gh pr create --title "..." --body "..." -gh pr view 123 -gh issue view --repo # For docs-writer -gh pr diff --repo # For docs-writer -``` - -### Jira MCP (for triage, docs-writer, prd, design, kcs) -```bash -# Invoked via MCP tools, not CLI directly -# Example JQL: "project = EDM AND issuetype = Bug AND resolution = Unresolved" -``` - -### Vale (for docs-writer) -```bash -vale path/to/file.adoc # Style/terminology validation -``` - ## Key Constraints 1. **No IDE-specific syntax**: All workflow content is plain markdown 2. **Relative paths only**: For symlink compatibility across install scopes 3. **Progressive disclosure**: SKILL.md stays under 30 lines 4. **No auto-advance in attended mode**: Workflows wait for user input between phases unless an explicit unattended mode is documented for that workflow -5. **Artifact persistence**: All significant outputs saved to .artifacts/ +5. **Artifact persistence**: All significant outputs saved to `.artifacts/{workflow-name}/{context}/` 6. **Read-only reviews**: skill-reviewer never modifies target skill files during review +## Installation + +Install with `./install.sh ` (targets: `cursor`, `claude`, `gemini`, `all`). See README.md for scopes, options, and uninstall instructions. + +## Development + +See CONTRIBUTING.md for workflow structure conventions, path rules, testing, and installation internals. + ## File Organization ```text @@ -363,6 +117,6 @@ ai-workflows/ When a workflow invokes commands that could affect shared systems: - **Git operations**: Always verify with `git status` before destructive operations -- **PR/MR creation**: Confirm branch and base before pushing (bugfix uses GitHub, docs-writer uses GitLab) -- **Jira queries**: Triage is read-only, but always confirm project key before bulk operations -- **Documentation changes**: Run Vale validation before applying changes to repository files (docs-writer) +- **PR/MR creation**: Confirm branch and base before pushing +- **Jira writes**: Only cve-fix `/close` and design `/sync` write to Jira; both require explicit approval +- **Documentation changes**: Run Vale validation before applying changes to repository files diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b20f1a..07c2db7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,6 +82,17 @@ All internal file references must be **relative to the file's own location**: This ensures symlinks resolve paths correctly regardless of where the workflow is installed. +## Installation Internals + +The installer (`install.sh`) auto-discovers workflows by scanning for `*/SKILL.md` at the repo root. No script changes are needed when adding a workflow. + +**Claude Code integration**: The installer: +1. Appends workflow references to `CLAUDE.md` (or `.claude/CLAUDE.md` for project-level) beneath the `# ai-workflows` marker +2. Symlinks workflows into `~/.claude/skills/` (or `.claude/skills/` for project-level) for slash command discovery +3. Removes stale references (old controller.md paths) to avoid duplicates + +**Uninstall** (`uninstall.sh`) mirrors the install logic with removal. + ## Testing Your Changes 1. Install locally: `./install.sh cursor` (or `all`). From 1ef5ee097d665f7d5d53567161a703d867aa8a18 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 7 May 2026 17:34:32 -0400 Subject: [PATCH 2/2] Fix CI validator and address CodeRabbit feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update validate-structure.sh to match the trimmed AGENTS.md format: - Remove checks for per-workflow artifact entries and workflow-specific notes sections in AGENTS.md (content now lives in each workflow's docs) - Add new check ensuring each workflow's README.md documents its artifact paths, catching the same "forgot to document artifacts" problem at the source rather than in a summary Add artifacts section to ai-ready/README.md to satisfy the new check (no .artifacts/ output — writes directly to the target project). Replace home-absolute path ~/.claude/skills/ in CONTRIBUTING.md with path-agnostic wording per CodeRabbit feedback. Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/scripts/validate-structure.sh | 27 +++++++++++++++------------ CONTRIBUTING.md | 2 +- ai-ready/README.md | 4 ++++ 3 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.github/scripts/validate-structure.sh b/.github/scripts/validate-structure.sh index 9eb7b05..6df2120 100755 --- a/.github/scripts/validate-structure.sh +++ b/.github/scripts/validate-structure.sh @@ -111,17 +111,7 @@ for wf in "${workflows[@]}"; do fail "AGENTS.md: workflow list missing entry for '$wf'" fi - # 5b. Artifact management (lines like: - **workflow**: `.artifacts/...) - if ! grep -qF -- "- **${wf}**:" "$agents"; then - fail "AGENTS.md: artifact management missing entry for '$wf'" - fi - - # 5c. Workflow-Specific Notes (### heading) - if ! grep -qF -- "### ${wf}" "$agents"; then - fail "AGENTS.md: workflow-specific notes missing '### $wf' section" - fi - - # 5d. File organization tree (line containing the workflow dir name) + # 5b. File organization tree (line containing the workflow dir name) if ! sed -n '/^```text/,/^```/p' "$agents" | grep -qF -- "${wf}/"; then fail "AGENTS.md: file organization tree missing '$wf/'" fi @@ -143,7 +133,20 @@ done echo # --------------------------------------------------------------------------- -# 7. No absolute paths in skill files +# 7. Per-workflow README.md artifact documentation +# --------------------------------------------------------------------------- +echo "--- Workflow README artifact docs ---" +for wf in "${workflows[@]}"; do + readme_wf="$wf/README.md" + [ -f "$readme_wf" ] || continue + if ! grep -qF '.artifacts/' "$readme_wf"; then + fail "$readme_wf: missing artifact path documentation (.artifacts/ reference)" + fi +done +echo + +# --------------------------------------------------------------------------- +# 8. No absolute paths in skill files # --------------------------------------------------------------------------- echo "--- Absolute path check ---" for wf in "${workflows[@]}"; do diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07c2db7..7d2eacf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,7 +88,7 @@ The installer (`install.sh`) auto-discovers workflows by scanning for `*/SKILL.m **Claude Code integration**: The installer: 1. Appends workflow references to `CLAUDE.md` (or `.claude/CLAUDE.md` for project-level) beneath the `# ai-workflows` marker -2. Symlinks workflows into `~/.claude/skills/` (or `.claude/skills/` for project-level) for slash command discovery +2. Symlinks workflows into the user-level Claude skills directory (or `.claude/skills/` for project-level) for slash command discovery 3. Removes stale references (old controller.md paths) to avoid duplicates **Uninstall** (`uninstall.sh`) mirrors the install logic with removal. diff --git a/ai-ready/README.md b/ai-ready/README.md index 67fa09a..7c3ba10 100644 --- a/ai-ready/README.md +++ b/ai-ready/README.md @@ -35,6 +35,10 @@ ai-ready/ update.md # The scan and update skill ``` +## Artifacts + +No `.artifacts/` output — this workflow writes directly to the target project's `AGENTS.md`. + ## How It Works 1. Checks for an existing `AGENTS.md` (reads it as the baseline if found) and scans for all AI convention files in the project