From f6b48a0925ba2c6e00d95268c0e2cc6ab4100179 Mon Sep 17 00:00:00 2001 From: jacob-pattern Date: Fri, 15 May 2026 13:35:37 -0600 Subject: [PATCH] Align Code Mint with interface outcomes Keep Code Mint focused on repo-level onboarding outcomes by removing Vector/Layer 4 coupling and narrowing AIDLC references to lightweight audit discipline. Co-authored-by: Cursor --- .agents/code-mint-status.json | 3 +- .../SKILL.md | 27 ++++-- .../SKILL.md | 10 +-- .../SKILL.md | 29 +++++-- .../SKILL.md | 29 +++++-- .../references/smoke-test-guide.md | 0 .../SKILL.md | 12 +-- .../SKILL.md | 27 ++++-- .../references/testing-standards.md | 0 .../SKILL.md | 10 +-- .../SKILL.md | 6 +- .../references/recipes.md | 0 .../SKILL.md | 4 +- .../references/ticket-formats.md | 0 .../SKILL.md | 27 ++++-- .../references/readiness-checklist.md | 2 +- .../SKILL.md | 8 +- .../references/agents-md-guide.md | 4 +- .../references/root-agents-md-template.md | 0 .../subdirectory-agents-md-template.md | 0 .../SKILL.md | 87 ++++++++++++------- .github/ISSUE_TEMPLATE/bug-report.md | 2 +- .github/ISSUE_TEMPLATE/documentation.md | 2 +- AGENTS.md | 10 +-- CONTRIBUTING.md | 2 +- README.md | 28 +++--- docs/adoption-guide.md | 14 +-- docs/framework.md | 37 +++++--- docs/onboarding-checklist.md | 12 +-- docs/outcomes.md | 18 ++-- docs/skill-development.md | 39 +++++---- docs/skills-status.md | 24 ++--- 32 files changed, 303 insertions(+), 170 deletions(-) rename .agents/skills/{autonomy--env-auditor => autonomy-env-auditor}/SKILL.md (81%) rename .agents/skills/{autonomy--env-creator => autonomy-env-creator}/SKILL.md (95%) rename .agents/skills/{autonomy--sre-auditor => autonomy-sre-auditor}/SKILL.md (81%) rename .agents/skills/{autonomy--runtime-auditor => autonomy-staging-auditor}/SKILL.md (86%) rename .agents/skills/{autonomy--runtime-auditor => autonomy-staging-auditor}/references/smoke-test-guide.md (100%) rename .agents/skills/{autonomy--runtime-creator => autonomy-staging-creator}/SKILL.md (89%) rename .agents/skills/{autonomy--test-readiness-auditor => autonomy-testing-auditor}/SKILL.md (81%) rename .agents/skills/{autonomy--test-readiness-auditor => autonomy-testing-auditor}/references/testing-standards.md (100%) rename .agents/skills/{autonomy--test-readiness-creator => autonomy-testing-creator}/SKILL.md (92%) rename .agents/skills/{autonomy--sre-agent => interface-sre-agent}/SKILL.md (98%) rename .agents/skills/{autonomy--sre-agent => interface-sre-agent}/references/recipes.md (100%) rename .agents/skills/{clarity--ticket-writer => interface-ticket-writer}/SKILL.md (96%) rename .agents/skills/{clarity--ticket-writer => interface-ticket-writer}/references/ticket-formats.md (100%) rename .agents/skills/{legibility--auditor => legibility-auditor}/SKILL.md (85%) rename .agents/skills/{legibility--auditor => legibility-auditor}/references/readiness-checklist.md (97%) rename .agents/skills/{legibility--enhancer => legibility-enhancer}/SKILL.md (95%) rename .agents/skills/{legibility--enhancer => legibility-enhancer}/references/agents-md-guide.md (99%) rename .agents/skills/{legibility--enhancer => legibility-enhancer}/references/root-agents-md-template.md (100%) rename .agents/skills/{legibility--enhancer => legibility-enhancer}/references/subdirectory-agents-md-template.md (100%) rename .agents/skills/{meta--onboarding => meta-onboarding}/SKILL.md (81%) diff --git a/.agents/code-mint-status.json b/.agents/code-mint-status.json index 2f10071..cad6ec1 100644 --- a/.agents/code-mint-status.json +++ b/.agents/code-mint-status.json @@ -1,8 +1,9 @@ { - "code_mint": "1.0", + "code_mint": "1.1", "scope": ".", "onboarded_at": null, "last_validated": null, + "heritage": null, "outcomes": { "validate_current_state": { "status": "Not Started", "date": null }, "navigate": { "status": "Not Started", "date": null }, diff --git a/.agents/skills/autonomy--env-auditor/SKILL.md b/.agents/skills/autonomy-env-auditor/SKILL.md similarity index 81% rename from .agents/skills/autonomy--env-auditor/SKILL.md rename to .agents/skills/autonomy-env-auditor/SKILL.md index eceaa9c..7818c0c 100644 --- a/.agents/skills/autonomy--env-auditor/SKILL.md +++ b/.agents/skills/autonomy-env-auditor/SKILL.md @@ -1,12 +1,21 @@ --- -name: autonomy--env-auditor -description: Audit whether a repository's environment variable configuration allows an agent to load all required .env variables from scratch. Use when evaluating a new repository's agent-readiness, when environment loading fails during agent setup, or as part of an initial harness assessment. Do not use when .env files already load correctly and the goal is to add a single new variable, or when creating env loading capability (use autonomy--env-creator). +name: autonomy-env-auditor +description: Audit whether a repository's environment variable configuration allows an agent to load all required .env variables from scratch. Use when evaluating a new repository's agent-readiness, when environment loading fails during agent setup, or as part of an initial harness assessment. Do not use when .env files already load correctly and the goal is to add a single new variable, or when creating env loading capability (use autonomy-env-creator). --- # Environment Auditor Evaluate whether an agent can configure and load all required environment variables from a cold start — with zero pre-existing `.env` files or manual setup. +## Discipline + +This auditor follows code-mint's shared auditor discipline: + +- **Depth option** — default `standard`; use `quick` for a sanity check on a recently audited repo or `deep` for legacy codebases, quarterly refreshes, or high-risk readiness claims. Heritage classification from `meta-onboarding` Phase 0 sets a sensible default. +- **Calibration** — every report ends with a Calibration section naming the depth used, confidence level, what was not checked, and what would raise confidence. This is a required artifact, not a disclaimer. + +This discipline is inspired by AWS AI-DLC's adaptive-depth and overconfidence-prevention ideas, but code-mint does not vendor or implement the full AI-DLC workflow. + ## Step 1: Discover Environment Requirements 1. **Find all environment variable references** in the codebase: @@ -60,7 +69,7 @@ Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. -Write the report to `.agents/reports/autonomy--env-auditor-audit.md`: +Write the report to `.agents/reports/autonomy-env-auditor-audit.md`: ``` # Environment Audit Report @@ -87,13 +96,21 @@ Write the report to `.agents/reports/autonomy--env-auditor-audit.md`: - **Current State:** [what exists] - **Required State:** [what should exist] - **Recommended Action:** [specific step] -- **Next Skill / Step:** [e.g., Run `autonomy--env-creator`] +- **Next Skill / Step:** [e.g., Run `autonomy-env-creator`] ## Cold Start Blockers [List of variables that prevent application startup] ## Next Steps -Run `autonomy--env-creator` to remediate findings. +Run `autonomy-env-creator` to remediate findings. + +## Calibration +**Depth:** [quick / standard / deep] +**Confidence:** [High / Medium / Low] — [one-sentence reason] +**Not checked:** +- [specific area + reason] +**To raise confidence:** +- [specific next step] ``` After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--env-creator/SKILL.md b/.agents/skills/autonomy-env-creator/SKILL.md similarity index 95% rename from .agents/skills/autonomy--env-creator/SKILL.md rename to .agents/skills/autonomy-env-creator/SKILL.md index 2d62d51..2d07950 100644 --- a/.agents/skills/autonomy--env-creator/SKILL.md +++ b/.agents/skills/autonomy-env-creator/SKILL.md @@ -1,17 +1,17 @@ --- -name: autonomy--env-creator -description: Creates the capacity for an agent to load all environment variables from scratch, based on the output of autonomy--env-auditor. Use when an env audit report exists and environment loading needs to be remediated. Do not use when no audit report exists (run autonomy--env-auditor first) or when debugging a single missing variable. +name: autonomy-env-creator +description: Creates the capacity for an agent to load all environment variables from scratch, based on the output of autonomy-env-auditor. Use when an env audit report exists and environment loading needs to be remediated. Do not use when no audit report exists (run autonomy-env-auditor first) or when debugging a single missing variable. --- # Environment Creator -Build out a repository's environment variable configuration so that an agent (or new developer) can go from zero to a fully configured `.env` in a single command. Based on findings from `autonomy--env-auditor`. +Build out a repository's environment variable configuration so that an agent (or new developer) can go from zero to a fully configured `.env` in a single command. Based on findings from `autonomy-env-auditor`. Prefer one documented bootstrap path that writes local env config from the repo's real source of truth. In many repos that is `scripts/env.sh`. A `.env.example` file can still exist, but it should be secondary. ## Prerequisites -Read the audit report at `.agents/reports/autonomy--env-auditor-audit.md`. If no report exists, instruct the user to run `autonomy--env-auditor` first. +Read the audit report at `.agents/reports/autonomy-env-auditor-audit.md`. If no report exists, instruct the user to run `autonomy-env-auditor` first. Before changing anything: @@ -242,5 +242,5 @@ Update the project's AGENTS.md and/or README to include: 3. Start the application and verify it boots successfully. 4. If generation or startup verification fails, keep the old `.env` in place or restore it from the backup before trying again. 5. If a `.env.example` file exists, keep it as a reference or compatibility file only. Point it to the primary bootstrap path if helpful. -6. Archive the audit report to `.agents/reports/completed/autonomy--env-auditor-audit-{YYYY-MM-DD}.md`. +6. Archive the audit report to `.agents/reports/completed/autonomy-env-auditor-audit-{YYYY-MM-DD}.md`. 7. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--sre-auditor/SKILL.md b/.agents/skills/autonomy-sre-auditor/SKILL.md similarity index 81% rename from .agents/skills/autonomy--sre-auditor/SKILL.md rename to .agents/skills/autonomy-sre-auditor/SKILL.md index 3dbc24c..364b6f1 100644 --- a/.agents/skills/autonomy--sre-auditor/SKILL.md +++ b/.agents/skills/autonomy-sre-auditor/SKILL.md @@ -1,6 +1,6 @@ --- -name: autonomy--sre-auditor -description: Audit whether an agent has working access to the SRE CLIs the project uses — version control host CLI, cloud provider CLI, and observability CLI. Tests each connection and reports access gaps. The steps below use GitHub CLI, AWS CLI, and Datadog Pup as a worked example; adapt for your project's actual tooling. Use when setting up a new agent environment, troubleshooting tool access, or as part of an initial harness assessment. Do not use when debugging a specific production issue (use autonomy--sre-agent) or when auditing general runtime readiness (use autonomy--runtime-auditor). +name: autonomy-sre-auditor +description: Audit whether an agent has working access to the SRE CLIs the project uses — version control host CLI, cloud provider CLI, and observability CLI. Tests each connection and reports access gaps. The steps below use GitHub CLI, AWS CLI, and Datadog Pup as a worked example; adapt for your project's actual tooling. Use when setting up a new agent environment, troubleshooting tool access, or as part of an initial harness assessment. Do not use when debugging a specific production issue (use interface-sre-agent) or when auditing general runtime readiness (use autonomy-staging-auditor). --- # SRE Auditor @@ -9,6 +9,15 @@ Verify that an agent has authenticated, working access to the CLI tools required The steps below use **GitHub CLI, AWS CLI, and Datadog Pup** as a reference profile. If your project uses a different VCS host (e.g., GitLab, Azure DevOps), cloud provider (e.g., GCP, Azure), or observability platform (e.g., Grafana, New Relic, Prometheus), substitute the equivalent CLI and read-only verification commands while following the same audit structure. +## Discipline + +This auditor follows code-mint's shared auditor discipline: + +- **Depth option** — default `standard`; use `quick` for a sanity check on a recently audited repo or `deep` for legacy codebases, quarterly refreshes, or high-risk readiness claims. Heritage classification from `meta-onboarding` Phase 0 sets a sensible default. +- **Calibration** — every report ends with a Calibration section naming the depth used, confidence level, what was not checked, and what would raise confidence. This is a required artifact, not a disclaimer. + +This discipline is inspired by AWS AI-DLC's adaptive-depth and overconfidence-prevention ideas, but code-mint does not vendor or implement the full AI-DLC workflow. + ## Step 1: Audit GitHub CLI Access ### Check Installation @@ -107,7 +116,7 @@ For each monitoring tool, verify that output is machine-readable: - [ ] Traces connect requests across services - [ ] Error context includes stack traces, request IDs, and relevant input data -Machine-readable telemetry is required for `autonomy--sre-agent` to operate effectively. +Machine-readable telemetry is required for `interface-sre-agent` to operate effectively. ## Output @@ -115,7 +124,7 @@ Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. -Write the report to `.agents/reports/autonomy--sre-auditor-audit.md`: +Write the report to `.agents/reports/autonomy-sre-auditor-audit.md`: ``` # SRE Tooling Audit Report @@ -166,10 +175,18 @@ Write the report to `.agents/reports/autonomy--sre-auditor-audit.md`: - **Current State:** [what exists] - **Required State:** [what should exist] - **Recommended Action:** [specific step] -- **Next Skill / Step:** [e.g., Install/authenticate tooling manually, then re-run `autonomy--sre-auditor`; once ready, use `autonomy--sre-agent`] +- **Next Skill / Step:** [e.g., Install/authenticate tooling manually, then re-run `autonomy-sre-auditor`; once ready, use `interface-sre-agent`] ## Next Steps -Address findings to enable `autonomy--sre-agent` to operate effectively. If tooling or auth is missing, complete the manual install/authentication work first, then re-run `autonomy--sre-auditor`. +Address findings to enable `interface-sre-agent` to operate effectively. If tooling or auth is missing, complete the manual install/authentication work first, then re-run `autonomy-sre-auditor`. + +## Calibration +**Depth:** [quick / standard / deep] +**Confidence:** [High / Medium / Low] — [one-sentence reason] +**Not checked:** +- [specific area + reason] +**To raise confidence:** +- [specific next step] ``` After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `sre_investigation` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--runtime-auditor/SKILL.md b/.agents/skills/autonomy-staging-auditor/SKILL.md similarity index 86% rename from .agents/skills/autonomy--runtime-auditor/SKILL.md rename to .agents/skills/autonomy-staging-auditor/SKILL.md index 2c71cca..c8ba01f 100644 --- a/.agents/skills/autonomy--runtime-auditor/SKILL.md +++ b/.agents/skills/autonomy-staging-auditor/SKILL.md @@ -1,12 +1,21 @@ --- -name: autonomy--runtime-auditor -description: Audit whether an AI agent can go from a clean checkout to a runnable application or local runtime equivalent, without unsafe provisioning or destructive setup. Use when evaluating development or staging-like runtime readiness, onboarding a new project, or checking whether the agent can install dependencies, start services, and perform smoke checks. Do not use when evaluating test strategy and coverage depth (use autonomy--test-readiness-auditor) or when debugging a live production issue (use autonomy--sre-agent). +name: autonomy-staging-auditor +description: Audit whether an AI agent can go from a clean checkout to a runnable application or local runtime equivalent, without unsafe provisioning or destructive setup. Use when evaluating development or staging-like runtime readiness, onboarding a new project, or checking whether the agent can install dependencies, start services, and perform smoke checks. Do not use when evaluating test strategy and coverage depth (use autonomy-testing-auditor) or when debugging a live production issue (use interface-sre-agent). --- # Runtime Auditor Evaluate whether an agent can go from a clean checkout to a safe local runtime or staging-like equivalent, or to the closest safe local simulation of that environment. This skill focuses on install, setup, local services, startup, smoke checks, and infrastructure inspection. It does not require cloud provisioning. +## Discipline + +This auditor follows code-mint's shared auditor discipline: + +- **Depth option** — default `standard`; use `quick` for a sanity check on a recently audited repo or `deep` for legacy codebases, quarterly refreshes, or high-risk readiness claims. Heritage classification from `meta-onboarding` Phase 0 sets a sensible default. +- **Calibration** — every report ends with a Calibration section naming the depth used, confidence level, what was not checked, and what would raise confidence. This is a required artifact, not a disclaimer. + +This discipline is inspired by AWS AI-DLC's adaptive-depth and overconfidence-prevention ideas, but code-mint does not vendor or implement the full AI-DLC workflow. + ## Collaboration Rules Do not treat runtime readiness as a pure checklist exercise. Inspect the repository first, then ask only for the operational context the codebase cannot answer confidently. @@ -57,7 +66,7 @@ Check whether the application dependencies can be installed autonomously: ## Step 2: Evaluate Environment and Configuration Handoff -Cross-reference `autonomy--env-auditor` findings if that report exists. +Cross-reference `autonomy-env-auditor` findings if that report exists. - [ ] The runtime depends on a documented env loading path - [ ] Required local or development-safe values are available @@ -134,7 +143,7 @@ Ensure the report directories exist: `mkdir -p .agents/reports/completed && touc Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. -Write the report to `.agents/reports/autonomy--runtime-auditor-audit.md`: +Write the report to `.agents/reports/autonomy-staging-auditor-audit.md`: ```markdown # Runtime Audit Report @@ -189,10 +198,18 @@ Write the report to `.agents/reports/autonomy--runtime-auditor-audit.md`: - **Current State:** [what exists] - **Required State:** [what should exist] - **Recommended Action:** [specific step] -- **Next Skill / Step:** [for example, run `autonomy--runtime-creator`] +- **Next Skill / Step:** [for example, run `autonomy-staging-creator`] ## Next Steps -Run `autonomy--runtime-creator` to remediate findings. +Run `autonomy-staging-creator` to remediate findings. + +## Calibration +**Depth:** [quick / standard / deep] +**Confidence:** [High / Medium / Low] — [one-sentence reason] +**Not checked:** +- [specific area + reason] +**To raise confidence:** +- [specific next step] ``` After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--runtime-auditor/references/smoke-test-guide.md b/.agents/skills/autonomy-staging-auditor/references/smoke-test-guide.md similarity index 100% rename from .agents/skills/autonomy--runtime-auditor/references/smoke-test-guide.md rename to .agents/skills/autonomy-staging-auditor/references/smoke-test-guide.md diff --git a/.agents/skills/autonomy--runtime-creator/SKILL.md b/.agents/skills/autonomy-staging-creator/SKILL.md similarity index 89% rename from .agents/skills/autonomy--runtime-creator/SKILL.md rename to .agents/skills/autonomy-staging-creator/SKILL.md index 402675c..d20bb6b 100644 --- a/.agents/skills/autonomy--runtime-creator/SKILL.md +++ b/.agents/skills/autonomy-staging-creator/SKILL.md @@ -1,15 +1,15 @@ --- -name: autonomy--runtime-creator -description: Builds the scripts, setup flow, and runtime documentation needed for an agent to install dependencies, start local services, boot the app, and run smoke checks from a clean checkout. Use when a runtime audit report exists and runtime readiness needs improvement. Do not use when no audit report exists (run autonomy--runtime-auditor first) or when the main gap is test coverage depth (use autonomy--test-readiness-creator). +name: autonomy-staging-creator +description: Builds the scripts, setup flow, and runtime documentation needed for an agent to install dependencies, start local services, boot the app, and run smoke checks from a clean checkout. Use when a runtime audit report exists and runtime readiness needs improvement. Do not use when no audit report exists (run autonomy-staging-auditor first) or when the main gap is test coverage depth (use autonomy-testing-creator). --- # Runtime Creator -Build out a repository's runtime readiness so that an agent can go from a clean checkout to a runnable application or local runtime equivalent. Base all work on `autonomy--runtime-auditor`. +Build out a repository's runtime readiness so that an agent can go from a clean checkout to a runnable application or local runtime equivalent. Base all work on `autonomy-staging-auditor`. ## Prerequisites -Read `.agents/reports/autonomy--runtime-auditor-audit.md`. If no report exists, instruct the user to run `autonomy--runtime-auditor` first. +Read `.agents/reports/autonomy-staging-auditor-audit.md`. If no report exists, instruct the user to run `autonomy-staging-auditor` first. ## Collaboration Rules @@ -26,7 +26,7 @@ When needed, ask the developer: - "Which local substitutions are acceptable compared with production?" - "Which runtime steps are safe to automate, and which must stay manual?" -For smoke-test patterns and safety boundaries, see [../autonomy--runtime-auditor/references/smoke-test-guide.md](../autonomy--runtime-auditor/references/smoke-test-guide.md). The guide lives with the auditor skill intentionally so runtime audit and remediation share one canonical document (`docs/skill-development.md` documents this cross-skill link pattern). +For smoke-test patterns and safety boundaries, see [../autonomy-staging-auditor/references/smoke-test-guide.md](../autonomy-staging-auditor/references/smoke-test-guide.md). The guide lives with the auditor skill intentionally so runtime audit and remediation share one canonical document (`docs/skill-development.md` documents this cross-skill link pattern). ## Step 1: Extract the Handoff Contract @@ -123,5 +123,5 @@ If any step still depends on human approval or real cloud setup, document that b ## Step 7: Archive -1. Archive the audit report to `.agents/reports/completed/autonomy--runtime-auditor-audit-{YYYY-MM-DD}.md` +1. Archive the audit report to `.agents/reports/completed/autonomy-staging-auditor-audit-{YYYY-MM-DD}.md` 2. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `smoke_path` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--test-readiness-auditor/SKILL.md b/.agents/skills/autonomy-testing-auditor/SKILL.md similarity index 81% rename from .agents/skills/autonomy--test-readiness-auditor/SKILL.md rename to .agents/skills/autonomy-testing-auditor/SKILL.md index fc00fd8..e1bec99 100644 --- a/.agents/skills/autonomy--test-readiness-auditor/SKILL.md +++ b/.agents/skills/autonomy-testing-auditor/SKILL.md @@ -1,12 +1,21 @@ --- -name: autonomy--test-readiness-auditor -description: Evaluate whether a repository's unit, integration, end-to-end, visual, contract, and CI test setup lets an AI agent self-verify changes through fast, isolated, and well-targeted automated feedback. Use when auditing test readiness, onboarding a new project, or assessing whether the agent can safely validate its own work. Do not use when the main question is app startup or runtime bootstrapping (use autonomy--runtime-auditor) or when debugging one failing test (use autonomy--sre-agent). +name: autonomy-testing-auditor +description: Evaluate whether a repository's unit, integration, end-to-end, visual, contract, and CI test setup lets an AI agent self-verify changes through fast, isolated, and well-targeted automated feedback. Use when auditing test readiness, onboarding a new project, or assessing whether the agent can safely validate its own work. Do not use when the main question is app startup or runtime bootstrapping (use autonomy-staging-auditor) or when debugging one failing test (use interface-sre-agent). --- # Test Readiness Auditor Evaluate whether the repository's tests provide the feedback loops needed for autonomous agent work. This includes unit, integration, end-to-end, visual or snapshot, contract, and CI testing strategy, along with speed, isolation, and developer ergonomics. An agent that cannot self-verify is a liability. +## Discipline + +This auditor follows code-mint's shared auditor discipline: + +- **Depth option** — default `standard`; use `quick` for a sanity check on a recently audited repo or `deep` for legacy codebases, quarterly refreshes, or high-risk readiness claims. Heritage classification from `meta-onboarding` Phase 0 sets a sensible default. +- **Calibration** — every report ends with a Calibration section naming the depth used, confidence level, what was not checked, and what would raise confidence. This is a required artifact, not a disclaimer. + +This discipline is inspired by AWS AI-DLC's adaptive-depth and overconfidence-prevention ideas, but code-mint does not vendor or implement the full AI-DLC workflow. + ## Step 1: Discover the Test Infrastructure 1. Identify the test framework or frameworks in use. @@ -75,7 +84,7 @@ Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. -Write the report to `.agents/reports/autonomy--test-readiness-auditor-audit.md`: +Write the report to `.agents/reports/autonomy-testing-auditor-audit.md`: ```markdown # Test Readiness Audit Report @@ -109,7 +118,7 @@ Write the report to `.agents/reports/autonomy--test-readiness-auditor-audit.md`: - **Current State:** [what exists] - **Required State:** [what should exist] - **Recommended Action:** [specific step] -- **Next Skill / Step:** [e.g., Run `autonomy--test-readiness-creator`] +- **Next Skill / Step:** [e.g., Run `autonomy-testing-creator`] ## Speed Assessment - Unit Test Speed: [Xms average] @@ -128,7 +137,15 @@ Write the report to `.agents/reports/autonomy--test-readiness-auditor-audit.md`: [Assessment with specific blockers if any] ## Next Steps -Run `autonomy--test-readiness-creator` to remediate findings. +Run `autonomy-testing-creator` to remediate findings. + +## Calibration +**Depth:** [quick / standard / deep] +**Confidence:** [High / Medium / Low] — [one-sentence reason] +**Not checked:** +- [specific area + reason] +**To raise confidence:** +- [specific next step] ``` After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `self_test` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--test-readiness-auditor/references/testing-standards.md b/.agents/skills/autonomy-testing-auditor/references/testing-standards.md similarity index 100% rename from .agents/skills/autonomy--test-readiness-auditor/references/testing-standards.md rename to .agents/skills/autonomy-testing-auditor/references/testing-standards.md diff --git a/.agents/skills/autonomy--test-readiness-creator/SKILL.md b/.agents/skills/autonomy-testing-creator/SKILL.md similarity index 92% rename from .agents/skills/autonomy--test-readiness-creator/SKILL.md rename to .agents/skills/autonomy-testing-creator/SKILL.md index db8cefb..fde5bbb 100644 --- a/.agents/skills/autonomy--test-readiness-creator/SKILL.md +++ b/.agents/skills/autonomy-testing-creator/SKILL.md @@ -1,17 +1,17 @@ --- -name: autonomy--test-readiness-creator -description: Builds the test setup, test utilities, and high-priority coverage needed for an agent to self-verify changes across unit, integration, end-to-end, visual, contract, and CI workflows. Use when a test readiness audit report exists and the testing setup needs improvement. Do not use when no audit report exists (run autonomy--test-readiness-auditor first) or when debugging one failing test (use autonomy--sre-agent). +name: autonomy-testing-creator +description: Builds the test setup, test utilities, and high-priority coverage needed for an agent to self-verify changes across unit, integration, end-to-end, visual, contract, and CI workflows. Use when a test readiness audit report exists and the testing setup needs improvement. Do not use when no audit report exists (run autonomy-testing-auditor first) or when debugging one failing test (use interface-sre-agent). --- # Test Readiness Creator -Build out a repository's testing setup so it supports autonomous agent verification, based on findings from `autonomy--test-readiness-auditor`. +Build out a repository's testing setup so it supports autonomous agent verification, based on findings from `autonomy-testing-auditor`. **Scope:** Full test coverage is built incrementally, not in one session. During initial onboarding, focus on establishing the test framework, creating test utilities, and writing tests for the 3-5 highest-risk modules. Expand coverage in subsequent sessions. ## Prerequisites -Read the audit report at `.agents/reports/autonomy--test-readiness-auditor-audit.md`. If no report exists, instruct the user to run `autonomy--test-readiness-auditor` first. +Read the audit report at `.agents/reports/autonomy-testing-auditor-audit.md`. If no report exists, instruct the user to run `autonomy-testing-auditor` first. ## Step 1: Extract the Handoff Contract @@ -106,5 +106,5 @@ Before changing CI behavior, ask for explicit approval if the change will block 1. Run the full test suite and confirm all new tests pass. 2. Verify per-file test execution works with the documented command. 3. Confirm test speed meets benchmarks where practical. -4. Archive the audit report to `.agents/reports/completed/autonomy--test-readiness-auditor-audit-{YYYY-MM-DD}.md`. +4. Archive the audit report to `.agents/reports/completed/autonomy-testing-auditor-audit-{YYYY-MM-DD}.md`. 5. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `self_test` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/autonomy--sre-agent/SKILL.md b/.agents/skills/interface-sre-agent/SKILL.md similarity index 98% rename from .agents/skills/autonomy--sre-agent/SKILL.md rename to .agents/skills/interface-sre-agent/SKILL.md index c1176a3..b0d476f 100644 --- a/.agents/skills/autonomy--sre-agent/SKILL.md +++ b/.agents/skills/interface-sre-agent/SKILL.md @@ -1,6 +1,6 @@ --- -name: autonomy--sre-agent -description: Diagnose production issues by querying logs, metrics, and traces from observability, cloud, and CI/CD CLIs. Use when investigating errors, debugging production issues, checking service health, reviewing CI/CD status, checking recent deployments, reproducing a reported bug with evidence, or when the user mentions logs, metrics, monitoring dashboards, container services, CI pipelines, or production incidents. Do not use when the issue is a known feature request or cosmetic change (use clarity--ticket-writer) or when auditing whether tools are accessible (use autonomy--sre-auditor). +name: interface-sre-agent +description: Diagnose production issues by querying logs, metrics, and traces from observability, cloud, and CI/CD CLIs. Use when investigating errors, debugging production issues, checking service health, reviewing CI/CD status, checking recent deployments, reproducing a reported bug with evidence, or when the user mentions logs, metrics, monitoring dashboards, container services, CI pipelines, or production incidents. Do not use when the issue is a known feature request or cosmetic change (use interface-ticket-writer) or when auditing whether tools are accessible (use autonomy-sre-auditor). --- # SRE Agent @@ -13,7 +13,7 @@ This skill also serves as an onboarding proof tool. If the team wants to prove ` ## Prerequisites -Ensure these are available before running queries. If any fail, stop and tell the user what's missing. If multiple tools are unavailable, advise running `autonomy--sre-auditor` to diagnose access issues. +Ensure these are available before running queries. If any fail, stop and tell the user what's missing. If multiple tools are unavailable, advise running `autonomy-sre-auditor` to diagnose access issues. Also check whether the project-local `[CUSTOMIZE]` sections in this skill and `references/recipes.md` have been filled in for the current repository. If key identifiers such as service names, log groups, AWS profiles, repo owner/name, or deploy workflow are still placeholders, stop and ask the user to complete the onboarding customization step first rather than guessing. diff --git a/.agents/skills/autonomy--sre-agent/references/recipes.md b/.agents/skills/interface-sre-agent/references/recipes.md similarity index 100% rename from .agents/skills/autonomy--sre-agent/references/recipes.md rename to .agents/skills/interface-sre-agent/references/recipes.md diff --git a/.agents/skills/clarity--ticket-writer/SKILL.md b/.agents/skills/interface-ticket-writer/SKILL.md similarity index 96% rename from .agents/skills/clarity--ticket-writer/SKILL.md rename to .agents/skills/interface-ticket-writer/SKILL.md index 51e20b4..d71d6b6 100644 --- a/.agents/skills/clarity--ticket-writer/SKILL.md +++ b/.agents/skills/interface-ticket-writer/SKILL.md @@ -1,6 +1,6 @@ --- -name: clarity--ticket-writer -description: Collaborates with a product owner, TPM, or engineer to refine vague requests into high-quality work tickets optimized for agent one-shot execution. Use when writing tickets, refining requirements, reviewing feature requests, or when a stakeholder submits a new task. Do not use when debugging an existing issue (use autonomy--sre-agent) or when auditing codebase readiness (use legibility--auditor). +name: interface-ticket-writer +description: Collaborates with a product owner, TPM, or engineer to refine vague requests into high-quality work tickets optimized for agent one-shot execution. Use when writing tickets, refining requirements, reviewing feature requests, or when a stakeholder submits a new task. Do not use when debugging an existing issue (use interface-sre-agent) or when auditing codebase readiness (use legibility-auditor). --- # Ticket Writer diff --git a/.agents/skills/clarity--ticket-writer/references/ticket-formats.md b/.agents/skills/interface-ticket-writer/references/ticket-formats.md similarity index 100% rename from .agents/skills/clarity--ticket-writer/references/ticket-formats.md rename to .agents/skills/interface-ticket-writer/references/ticket-formats.md diff --git a/.agents/skills/legibility--auditor/SKILL.md b/.agents/skills/legibility-auditor/SKILL.md similarity index 85% rename from .agents/skills/legibility--auditor/SKILL.md rename to .agents/skills/legibility-auditor/SKILL.md index 56b1a4d..906fb48 100644 --- a/.agents/skills/legibility--auditor/SKILL.md +++ b/.agents/skills/legibility-auditor/SKILL.md @@ -1,12 +1,21 @@ --- -name: legibility--auditor -description: Audits a repository's documentation coverage and agent-readiness by evaluating AGENTS.md placement, progressive disclosure quality, and UX intent documentation. Use when evaluating repository structure, auditing documentation coverage, assessing agent-readiness, or onboarding a codebase to agent-first practices. Do not use when creating or editing AGENTS.md files directly (use legibility--enhancer instead). +name: legibility-auditor +description: Audits a repository's documentation coverage and agent-readiness by evaluating AGENTS.md placement, progressive disclosure quality, and UX intent documentation. Use when evaluating repository structure, auditing documentation coverage, assessing agent-readiness, or onboarding a codebase to agent-first practices. Do not use when creating or editing AGENTS.md files directly (use legibility-enhancer instead). --- # Legibility Auditor Evaluate how thoroughly a repository is mapped for autonomous agent navigation and produce an Agent Readiness Report. A well-mapped repository enables an agent to understand both *how* something works (technical implementation) and *why* it exists (user experience intent). This skill identifies where that mapping is missing, incomplete, or misleading. The findings support the **`Navigate`** outcome defined in `docs/outcomes.md`. +## Discipline + +This auditor follows code-mint's shared auditor discipline: + +- **Depth option** — default `standard`; use `quick` for a sanity check on a recently audited repo or `deep` for legacy codebases, quarterly refreshes, or high-risk readiness claims. Heritage classification from `meta-onboarding` Phase 0 sets a sensible default. +- **Calibration** — every report ends with a Calibration section naming the depth used, confidence level, what was not checked, and what would raise confidence. This is a required artifact, not a disclaimer. + +This discipline is inspired by AWS AI-DLC's adaptive-depth and overconfidence-prevention ideas, but code-mint does not vendor or implement the full AI-DLC workflow. + ## Step 1: Crawl the Repository Structure 1. List all directories and subdirectories. @@ -82,7 +91,7 @@ Ensure the report directory exists: `mkdir -p .agents/reports/completed && touch Ensure `.gitignore` ignores generated report contents while preserving the directories with their `.gitkeep` files. -Write the report to `.agents/reports/legibility--auditor-audit.md` using this structure: +Write the report to `.agents/reports/legibility-auditor-audit.md` using this structure: ``` # Legibility Audit Report @@ -117,10 +126,18 @@ Write the report to `.agents/reports/legibility--auditor-audit.md` using this st - **Current State:** [what exists now] - **Required State:** [what should exist] - **Recommended Action:** [specific step] -- **Next Skill / Step:** [e.g., Run `legibility--enhancer` for this module] +- **Next Skill / Step:** [e.g., Run `legibility-enhancer` for this module] ## Next Steps -Run `legibility--enhancer` to collaboratively remediate findings. +Run `legibility-enhancer` to collaboratively remediate findings. + +## Calibration +**Depth:** [quick / standard / deep] +**Confidence:** [High / Medium / Low] — [one-sentence reason] +**Not checked:** +- [specific area + reason] +**To raise confidence:** +- [specific next step] ``` After writing the report, update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `navigate` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. diff --git a/.agents/skills/legibility--auditor/references/readiness-checklist.md b/.agents/skills/legibility-auditor/references/readiness-checklist.md similarity index 97% rename from .agents/skills/legibility--auditor/references/readiness-checklist.md rename to .agents/skills/legibility-auditor/references/readiness-checklist.md index f577161..6d80e52 100644 --- a/.agents/skills/legibility--auditor/references/readiness-checklist.md +++ b/.agents/skills/legibility-auditor/references/readiness-checklist.md @@ -1,6 +1,6 @@ # Agent Readiness Checklist -Detailed scoring criteria for each of the eight **readiness dimensions** used only by this audit. These are not the same as the three framework pillars (Legibility, Autonomy, Clarity) in `docs/framework.md`. Score each dimension from Level 0 (Ad Hoc) to Level 4 (Optimized). +Detailed scoring criteria for each of the eight **readiness dimensions** used only by this audit. These are not the same as the three framework pillars (Legibility, Autonomy, Human-AI Interface) in `docs/framework.md`. Score each dimension from Level 0 (Ad Hoc) to Level 4 (Optimized). This rubric supports the **`Navigate`** north-star outcome in `docs/outcomes.md` by measuring how well the repo is mapped for agent navigation and related hygiene. diff --git a/.agents/skills/legibility--enhancer/SKILL.md b/.agents/skills/legibility-enhancer/SKILL.md similarity index 95% rename from .agents/skills/legibility--enhancer/SKILL.md rename to .agents/skills/legibility-enhancer/SKILL.md index d4df0ac..f376589 100644 --- a/.agents/skills/legibility--enhancer/SKILL.md +++ b/.agents/skills/legibility-enhancer/SKILL.md @@ -1,6 +1,6 @@ --- -name: legibility--enhancer -description: Collaboratively walks a human through creating high-quality AGENTS.md files throughout a codebase, implementing progressive disclosure architecture. Use when creating or updating AGENTS.md files, onboarding a repository to agent-first practices, or remediating findings from legibility--auditor. Do not use when evaluating existing documentation coverage (use legibility--auditor) or when creating agent skills (follow `docs/skill-development.md` instead). +name: legibility-enhancer +description: Collaboratively walks a human through creating high-quality AGENTS.md files throughout a codebase, implementing progressive disclosure architecture. Use when creating or updating AGENTS.md files, onboarding a repository to agent-first practices, or remediating findings from legibility-auditor. Do not use when evaluating existing documentation coverage (use legibility-auditor) or when creating agent skills (follow `docs/skill-development.md` instead). --- # Legibility Enhancer @@ -9,7 +9,7 @@ Walk through the process of creating high-quality AGENTS.md files with a human c ## Prerequisites -If a legibility audit report exists at `.agents/reports/legibility--auditor-audit.md`, read it first and prioritize directories flagged as missing AGENTS.md files. If no report exists, begin with Step 1. +If a legibility audit report exists at `.agents/reports/legibility-auditor-audit.md`, read it first and prioritize directories flagged as missing AGENTS.md files. If no report exists, begin with Step 1. ## Collaboration Rules @@ -155,7 +155,7 @@ Subdirectory `AGENTS.md` files **override** parent files — they do not merge. 1. Review all created AGENTS.md files for accuracy and completeness. 2. Confirm all build/test commands work by running them. 3. Summarize which directories received local guidance, which were intentionally deferred as simple, and why. -4. If a legibility audit report was used, archive it to `.agents/reports/completed/legibility--auditor-audit-{YYYY-MM-DD}.md`. +4. If a legibility audit report was used, archive it to `.agents/reports/completed/legibility-auditor-audit-{YYYY-MM-DD}.md`. 5. Update `docs/onboarding-checklist.md` and `.agents/code-mint-status.json` with the current `navigate` outcome status and date. Optionally update `docs/skills-status.md` if the repository keeps the compatibility view. ## Detailed Templates diff --git a/.agents/skills/legibility--enhancer/references/agents-md-guide.md b/.agents/skills/legibility-enhancer/references/agents-md-guide.md similarity index 99% rename from .agents/skills/legibility--enhancer/references/agents-md-guide.md rename to .agents/skills/legibility-enhancer/references/agents-md-guide.md index fdc8462..842484b 100644 --- a/.agents/skills/legibility--enhancer/references/agents-md-guide.md +++ b/.agents/skills/legibility-enhancer/references/agents-md-guide.md @@ -1,6 +1,6 @@ # AGENTS.md Templates and Examples -Use this guide when creating or reviewing `AGENTS.md` files with `legibility--enhancer`. +Use this guide when creating or reviewing `AGENTS.md` files with `legibility-enhancer`. ## Authoring Principles @@ -9,7 +9,7 @@ Use this guide when creating or reviewing `AGENTS.md` files with `legibility--en - Prefer concise, high-signal instructions over exhaustive inventory. - Remove sections or rows that do not apply. Never leave `[CUSTOMIZE]` markers behind. - Draft from repository evidence first, then ask the human for UX intent, hidden assumptions, and corrections. -- When this `AGENTS.md` governs a scoped directory inside a monorepo (not the git repository root), read the repository root `README.md` and any `README.md` on the path to the scope before drafting, and pull deploy-, CI-, or environment-relevant facts into the scoped file or explicit cross-references (same posture as `legibility--enhancer` Step 1). +- When this `AGENTS.md` governs a scoped directory inside a monorepo (not the git repository root), read the repository root `README.md` and any `README.md` on the path to the scope before drafting, and pull deploy-, CI-, or environment-relevant facts into the scoped file or explicit cross-references (same posture as `legibility-enhancer` Step 1). ## Canonical Root Structure diff --git a/.agents/skills/legibility--enhancer/references/root-agents-md-template.md b/.agents/skills/legibility-enhancer/references/root-agents-md-template.md similarity index 100% rename from .agents/skills/legibility--enhancer/references/root-agents-md-template.md rename to .agents/skills/legibility-enhancer/references/root-agents-md-template.md diff --git a/.agents/skills/legibility--enhancer/references/subdirectory-agents-md-template.md b/.agents/skills/legibility-enhancer/references/subdirectory-agents-md-template.md similarity index 100% rename from .agents/skills/legibility--enhancer/references/subdirectory-agents-md-template.md rename to .agents/skills/legibility-enhancer/references/subdirectory-agents-md-template.md diff --git a/.agents/skills/meta--onboarding/SKILL.md b/.agents/skills/meta-onboarding/SKILL.md similarity index 81% rename from .agents/skills/meta--onboarding/SKILL.md rename to .agents/skills/meta-onboarding/SKILL.md index 3c5ce16..6c04e71 100644 --- a/.agents/skills/meta--onboarding/SKILL.md +++ b/.agents/skills/meta-onboarding/SKILL.md @@ -1,5 +1,5 @@ --- -name: meta--onboarding +name: meta-onboarding description: Step-by-step playbook that transforms a repository for AI-first development. It scopes the repository, runs read-only audits, maintains an outcome-driven checklist, guides collaborative improvements, and verifies the results with evidence. Use when onboarding a new repository, when a user says "set up this repo for agents," or when starting a harness engineering transformation. Do not use when the repo is already onboarded and the goal is to run a single specific skill. --- @@ -28,7 +28,7 @@ Maintain these outcomes as the public promise of onboarding: Use `docs/outcomes.md` for the glossary and `docs/onboarding-checklist.md` as the system of record. -**Phases vs outcomes:** This playbook runs in five phases; a single phase may touch more than one north-star outcome when the proofs are coupled (for example Self-Test before Smoke Path, or bug repro alongside operational investigation). That does not relax the rule: prove and record each outcome separately in the checklist—one row at a time in the recommended order—before treating the next outcome as done. +**Phases vs outcomes:** This playbook runs in six phases (0–5); a single phase may touch more than one north-star outcome when the proofs are coupled (for example Self-Test before Smoke Path, or bug repro alongside operational investigation). That does not relax the rule: prove and record each outcome separately in the checklist—one row at a time in the recommended order—before treating the next outcome as done. Phase 0 calibrates heritage up front; Phases 1–5 prove and verify the six outcomes. ## Context Transfer @@ -162,34 +162,63 @@ Instead of forcing the user into a fixed path immediately, ask about preferences Then recommend the next phase sequence in plain language and ask for confirmation. +## Phase 0: Workspace Detection (Heritage Classification) + +Before running any auditors, classify the repo's heritage. This takes about two minutes and tells downstream auditors how to calibrate their depth. It borrows the greenfield/brownfield distinction from AWS AI-DLC, but keeps the classification lightweight and specific to code-mint onboarding. + +**Three classifications:** + +| Classification | Criteria | Implication | +|---|---|---| +| **Greenfield** | Less than ~6 months old, built with AI-first practices (AGENTS.md from day one, structured commits, tests present) | Auditors can run at `standard` depth; legibility gaps are easier to close with `legibility-enhancer` | +| **Brownfield** | Existing codebase being adapted for AI-first work; mixed documentation quality, some AGENTS.md, partial test coverage | Legibility auditor matters most — any score below Level 3 signals reverse engineering would be needed before safe agent autonomy | +| **Legacy** | Mature codebase with significant accumulated decisions, debt, or tribal knowledge; AGENTS.md absent; sparse or missing tests | Run auditors at `deep` depth; expect Phase 2 (Navigate) to be the longest phase | + +**Output:** Record the classification and the evidence supporting it in `.agents/reports/onboarding-summary.md` under a new section: + +```markdown +## Heritage Classification + +**Classification:** [Greenfield / Brownfield / Legacy] +**Evidence:** +- [specific signal, e.g., "repo created 2024-11-15, AGENTS.md present at root, test suite covers core modules"] +- [specific signal] + +**Downstream calibration:** +- Auditor depth: [quick / standard / deep] +- Primary risk area: [Legibility / Autonomy / Interface] +``` + +Use this classification to choose auditor depth and to explain why a repo may need more legibility work before autonomy improvements. + ## Phase 1: Assess The Current State Run applicable auditors to understand the current state. These are non-destructive, read-only assessments that produce reports to `.agents/reports/`. ### Step 1.1: Legibility Audit (Always Run) -**Skill:** `legibility--auditor` -**Output:** `.agents/reports/legibility--auditor-audit.md` +**Skill:** `legibility-auditor` +**Output:** `.agents/reports/legibility-auditor-audit.md` ### Step 1.2: Test Readiness Audit (Always Run) -**Skill:** `autonomy--test-readiness-auditor` -**Output:** `.agents/reports/autonomy--test-readiness-auditor-audit.md` +**Skill:** `autonomy-testing-auditor` +**Output:** `.agents/reports/autonomy-testing-auditor-audit.md` ### Step 1.3: Environment Audit (If Applicable) -**Skill:** `autonomy--env-auditor` -**Output:** `.agents/reports/autonomy--env-auditor-audit.md` +**Skill:** `autonomy-env-auditor` +**Output:** `.agents/reports/autonomy-env-auditor-audit.md` ### Step 1.4: Runtime Audit (If Applicable) -**Skill:** `autonomy--runtime-auditor` -**Output:** `.agents/reports/autonomy--runtime-auditor-audit.md` +**Skill:** `autonomy-staging-auditor` +**Output:** `.agents/reports/autonomy-staging-auditor-audit.md` ### Step 1.5: SRE Tooling Audit (If Applicable) -**Skill:** `autonomy--sre-auditor` -**Output:** `.agents/reports/autonomy--sre-auditor-audit.md` +**Skill:** `autonomy-sre-auditor` +**Output:** `.agents/reports/autonomy-sre-auditor-audit.md` ### Parallelism Rule @@ -239,8 +268,8 @@ This phase makes the codebase navigable enough for the agent to explain where wo ### Step 2.1: Create Root AGENTS.md -**Skill:** `legibility--enhancer` -**Input:** `.agents/reports/legibility--auditor-audit.md` +**Skill:** `legibility-enhancer` +**Input:** `.agents/reports/legibility-auditor-audit.md` **Root** means the onboarding scope root: the repository root when onboarding the full repo, or the scoped project directory when onboarding a monorepo package. @@ -278,8 +307,8 @@ Use the audit reports from Phase 1 to remediate the next approved gap. ### Step 3.1: Self-Test -**Skill:** `autonomy--test-readiness-creator` -**Input:** `.agents/reports/autonomy--test-readiness-auditor-audit.md` +**Skill:** `autonomy-testing-creator` +**Input:** `.agents/reports/autonomy-testing-auditor-audit.md` Focus on establishing the smallest trustworthy targeted test path for a high-value module or behavior. @@ -293,8 +322,8 @@ Mark `Self-Test` as `Proven` only when: ### Step 3.2: Environment Setup (If Applicable) -**Skill:** `autonomy--env-creator` -**Input:** `.agents/reports/autonomy--env-auditor-audit.md` +**Skill:** `autonomy-env-creator` +**Input:** `.agents/reports/autonomy-env-auditor-audit.md` Before any `.env` rewrite: @@ -305,8 +334,8 @@ Before any `.env` rewrite: ### Step 3.3: Smoke Path (If Applicable) -**Skill:** `autonomy--runtime-creator` -**Input:** `.agents/reports/autonomy--runtime-auditor-audit.md` +**Skill:** `autonomy-staging-creator` +**Input:** `.agents/reports/autonomy-staging-auditor-audit.md` Build setup scripts, local service flows, and smoke-check documentation only after the user approves those changes. The agent handles scripting; the human provides infrastructure context and confirms approval-gated decisions. @@ -322,7 +351,7 @@ Mark `Smoke Path` as `Proven` only when: ### Step 4.1: Bug Reproduction -Use `autonomy--sre-agent` or the local debugging workflow to turn one real bug report into a deterministic repro. Favor a failing test when possible. +Use `interface-sre-agent` or the local debugging workflow to turn one real bug report into a deterministic repro. Favor a failing test when possible. ### Proof Criteria For `Bug Reproduction` @@ -334,12 +363,12 @@ Mark `Bug Reproduction` as `Proven` only when: ### Step 4.2: SRE Investigation -If the project has logs, metrics, traces, or deployment history, customize and use `autonomy--sre-agent`. +If the project has logs, metrics, traces, or deployment history, customize and use `interface-sre-agent`. If the SRE agent needs project-local values, fill the `[CUSTOMIZE]` sections in: -- `.agents/skills/autonomy--sre-agent/SKILL.md` -- `.agents/skills/autonomy--sre-agent/references/recipes.md` +- `.agents/skills/interface-sre-agent/SKILL.md` +- `.agents/skills/interface-sre-agent/references/recipes.md` ### Proof Criteria For `SRE Investigation` @@ -384,10 +413,10 @@ Once the onboarding outcomes are proven, these ongoing skills become more useful | Skill | When To Use | |---|---| -| `clarity--ticket-writer` | When a PM or engineer has a new feature request or bug report | -| `autonomy--sre-agent` | When investigating production issues, errors, or incidents | -| `legibility--auditor` | Quarterly, to audit documentation coverage as the codebase evolves | -| `autonomy--test-readiness-auditor` | When test infrastructure changes or new modules are added | +| `interface-ticket-writer` | When a PM or engineer has a new feature request or bug report (inbound channel, human → system) | +| `interface-sre-agent` | When investigating production issues, errors, or incidents (outbound channel, system → human) | +| `legibility-auditor` | Quarterly, to audit documentation coverage as the codebase evolves | +| `autonomy-testing-auditor` | When test infrastructure changes or new modules are added | If the team later needs project-specific skills, treat that as follow-on library maintenance rather than part of the six-outcome proof loop. Use `docs/skill-development.md` as the canonical guide for authoring or revising those skills. @@ -396,6 +425,6 @@ If the team later needs project-specific skills, treat that as follow-on library - **Every PR:** If the PR changes module boundaries, conventions, or key behavior, update relevant `AGENTS.md` files. - **Monthly:** Refresh the smallest critical test paths and smoke-path evidence. - **Quarterly:** Re-run legibility and test-readiness audits to catch drift. -- **As needed:** Run `autonomy--sre-agent` for real failures and `clarity--ticket-writer` for new work. +- **As needed:** Run `interface-sre-agent` for real failures and `interface-ticket-writer` for new work. The durable progress checklist lives in `docs/onboarding-checklist.md`. Do not create a second parallel checklist in chat. diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md index 6e89526..2c3b376 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.md +++ b/.github/ISSUE_TEMPLATE/bug-report.md @@ -13,7 +13,7 @@ about: Report incorrect guidance, broken references, or issues with the onboardi ## Which skill, doc, or template is affected? - + ## Steps to reproduce diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 5c12317..edb2461 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -9,7 +9,7 @@ about: Propose improvements to docs, skills, templates, or cross-links ## Scope - + ## Notes diff --git a/AGENTS.md b/AGENTS.md index c05ad49..e0f3b88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,16 +27,16 @@ When working in this repo: | `docs/adoption-guide.md` | Detailed operator workflow for onboarding a target repo | | `docs/skills-status.md` | Compatibility matrix from skills to outcomes | | `docs/skill-development.md` | How to create and maintain skills | -| `.agents/skills/legibility--enhancer/references/` | Root and subdirectory `AGENTS.md` templates | +| `.agents/skills/legibility-enhancer/references/` | Root and subdirectory `AGENTS.md` templates | ## Skill Categories | Category | Meaning | |---|---| -| `meta--` | Onboarding and skill-library management | -| `legibility--` | Repo mapping and `AGENTS.md` creation | -| `autonomy--` | Self-verification, runtime readiness, env setup, and operational tooling (including `autonomy--sre-*`) | -| `clarity--` | Collaborative planning and executable tickets (post-core onboarding) | +| `meta-` | Onboarding and skill-library management | +| `legibility-` | Repo mapping and `AGENTS.md` creation | +| `autonomy-` | Self-verification, runtime readiness, env setup, and operational CLI access (`autonomy-sre-auditor`) | +| `interface-` | Human-AI Interface — bidirectional channel: `interface-ticket-writer` (human → system, refines requests) and `interface-sre-agent` (system → human, interprets operational signals) | ## Working Model diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05d52ff..9545388 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ See `docs/skill-development.md` for the canonical guide on creating and maintain ## Documentation change checklist (maintainers) -**Single source for outcome vocabulary:** `docs/outcomes.md` is the canonical glossary for outcome names, proof criteria, and primary skill mappings. When you change any of that, edit `docs/outcomes.md` first, then update pointers and checklists in `README.md`, `docs/framework.md`, `docs/onboarding-checklist.md`, `docs/skills-status.md`, `.agents/code-mint-status.json`, and `.agents/skills/meta--onboarding/SKILL.md` as needed so they stay aligned. +**Single source for outcome vocabulary:** `docs/outcomes.md` is the canonical glossary for outcome names, proof criteria, and primary skill mappings. When you change any of that, edit `docs/outcomes.md` first, then update pointers and checklists in `README.md`, `docs/framework.md`, `docs/onboarding-checklist.md`, `docs/skills-status.md`, `.agents/code-mint-status.json`, and `.agents/skills/meta-onboarding/SKILL.md` as needed so they stay aligned. After substantive edits to `README.md`, onboarding docs, or the copy bundle, quickly confirm: diff --git a/README.md b/README.md index 0342a7a..28e2487 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Harness work here is organized around three ideas. The [six outcomes](#outcome-m 1. **Legibility** — Can an AI agent navigate the codebase using durable in-repo guidance (`AGENTS.md`, maps, conventions)? 2. **Autonomy** — Can it self-verify with tests, safe runtime checks, and—where applicable—trusted access to operational tools and signals (not necessarily full production parity; see [`docs/framework.md`](docs/framework.md))? -3. **Clarity** — After the core outcomes are in place, can it collaborate on plans and tickets that are precise enough to execute (`clarity--ticket-writer`)? +3. **Human-AI Interface** — Is the bidirectional channel between humans and the system wired through the agent? Inbound: `interface-ticket-writer` refines vague requests into executable work. Outbound: `interface-sre-agent` interprets production signals (logs, metrics, traces, CI) and surfaces them to humans. ## At A Glance @@ -117,7 +117,7 @@ If you rely on a **single `.gitignore` at the git repository root** (common in m Open the folder that matches `TARGET_SCOPE` in your editor when you can (so relative paths resolve the same way for you and the agent). If you stay at the git repository root, name the scope in the prompt. Example: ```text -Use the meta--onboarding skill to onboard this repository. Start by assessing the current state, keep docs/onboarding-checklist.md updated as the system of record, and wait for approval before making changes. +Use the meta-onboarding skill to onboard this repository. Start by assessing the current state, keep docs/onboarding-checklist.md updated as the system of record, and wait for approval before making changes. ``` If onboarding only a subdirectory (when `TARGET_SCOPE` is not the repository root), add a line such as: `The onboarding scope is [path relative to repo root, e.g. apps/my-service]. Treat docs/, .agents/, and AGENTS.md paths as relative to that directory. Also read the git repository root README.md and any README.md files along the path from the repo root to that scope for repo-wide setup, deploy, CI, or environment notes that may not exist under the scope.` @@ -128,11 +128,11 @@ The first milestone is not "make changes." It is "prove the current state." Expected baseline artifacts: -- `.agents/reports/legibility--auditor-audit.md` -- `.agents/reports/autonomy--test-readiness-auditor-audit.md` -- `.agents/reports/autonomy--env-auditor-audit.md` when env loading applies -- `.agents/reports/autonomy--runtime-auditor-audit.md` when runtime applies -- `.agents/reports/autonomy--sre-auditor-audit.md` when cloud or monitoring applies +- `.agents/reports/legibility-auditor-audit.md` +- `.agents/reports/autonomy-testing-auditor-audit.md` +- `.agents/reports/autonomy-env-auditor-audit.md` when env loading applies +- `.agents/reports/autonomy-staging-auditor-audit.md` when runtime applies +- `.agents/reports/autonomy-sre-auditor-audit.md` when cloud or monitoring applies - `.agents/reports/onboarding-summary.md` - `docs/onboarding-checklist.md` updated with current statuses and next proofs @@ -149,7 +149,7 @@ The recommended order is: This keeps the work understandable and gives the user a visible sense of progress. -The `meta--onboarding` playbook sometimes groups related outcomes into one **phase** (for example Self-Test and Smoke Path, or Bug Reproduction and SRE Investigation) when the work naturally runs together. Treat that as scheduling convenience: in `docs/onboarding-checklist.md`, still record **one outcome at a time**—complete evidence for each outcome in the order above before leaning on the next. +The `meta-onboarding` playbook sometimes groups related outcomes into one **phase** (for example Self-Test and Smoke Path, or Bug Reproduction and SRE Investigation) when the work naturally runs together. Treat that as scheduling convenience: in `docs/onboarding-checklist.md`, still record **one outcome at a time**—complete evidence for each outcome in the order above before leaning on the next. When the copy is complete, you can remove the temporary source directory: @@ -184,10 +184,10 @@ The three pillars above are expanded in `docs/framework.md` with mechanical rule | `docs/outcomes.md` | The public north-star outcomes and evidence model | | `docs/onboarding-checklist.md` | The canonical outcome tracker template | | `docs/adoption-guide.md` | The detailed operator guide for onboarding a target repo | -| `docs/framework.md` | The conceptual foundation for harness engineering | +| `docs/framework.md` | The conceptual foundation for harness engineering (pillars, proof loops, and lightweight AIDLC-inspired audit discipline) | | `docs/skills-status.md` | Compatibility view that maps skills to outcomes | | `docs/skill-development.md` | How to create and maintain skills | -| `.agents/skills/legibility--enhancer/references/` | Fill-in-the-blank `AGENTS.md` templates and authoring guide | +| `.agents/skills/legibility-enhancer/references/` | Fill-in-the-blank `AGENTS.md` templates and authoring guide | ## Skill Categories @@ -195,10 +195,10 @@ The skill IDs stay stable even though the public story is outcome-first: | Category | Purpose | |---|---| -| `meta--` | Onboarding and skill-library management | -| `legibility--` | Making the repo navigable and well-documented | -| `autonomy--` | Self-verification, runtime readiness, env setup, and operational tooling (including `autonomy--sre-*`) | -| `clarity--` | Collaborative planning and executable tickets after core onboarding | +| `meta-` | Onboarding and skill-library management | +| `legibility-` | Making the repo navigable and well-documented | +| `autonomy-` | Self-verification, runtime readiness, env setup, and operational CLI access (`autonomy-sre-auditor`) | +| `interface-` | Human-AI Interface — bidirectional channel: `interface-ticket-writer` (human → system) and `interface-sre-agent` (system → human) | ## Governance diff --git a/docs/adoption-guide.md b/docs/adoption-guide.md index 0932836..a4ff0d6 100644 --- a/docs/adoption-guide.md +++ b/docs/adoption-guide.md @@ -25,7 +25,7 @@ Before asking the user to do much setup work, the onboarding flow should make th Open the folder that matches your onboarding scope when you can. If you work from the git repository root instead, state the scope in the prompt so paths for `docs/`, `.agents/`, and `AGENTS.md` stay unambiguous. Example: ```text -Use the meta--onboarding skill to onboard this repository for AI-first development, keep docs/onboarding-checklist.md updated as the system of record, summarize the findings, and wait for approval before making changes. +Use the meta-onboarding skill to onboard this repository for AI-first development, keep docs/onboarding-checklist.md updated as the system of record, summarize the findings, and wait for approval before making changes. ``` The prompt says "wait for approval before making changes" to reinforce assessment-first mode. Phase 1 runs read-only auditors; remediation begins only after the user reviews the baseline. @@ -46,11 +46,11 @@ Start with a read-only baseline: Typical baseline artifacts: -- `.agents/reports/legibility--auditor-audit.md` -- `.agents/reports/autonomy--test-readiness-auditor-audit.md` -- `.agents/reports/autonomy--env-auditor-audit.md` when applicable -- `.agents/reports/autonomy--runtime-auditor-audit.md` when applicable -- `.agents/reports/autonomy--sre-auditor-audit.md` when applicable +- `.agents/reports/legibility-auditor-audit.md` +- `.agents/reports/autonomy-testing-auditor-audit.md` +- `.agents/reports/autonomy-env-auditor-audit.md` when applicable +- `.agents/reports/autonomy-staging-auditor-audit.md` when applicable +- `.agents/reports/autonomy-sre-auditor-audit.md` when applicable - `.agents/reports/onboarding-summary.md` ### Outcome 2: Navigate @@ -119,7 +119,7 @@ Use small, reviewable PRs: 4. **Phase 4:** reproduction and SRE investigation workflows 5. **Phase 5:** verification refresh and optional activation of ongoing skills -These PR phases align with the playbook phases in the `meta--onboarding` skill (assessment → navigation → self-test/smoke → bug repro/SRE → verify/activate). Use the skill for step-by-step operator detail; use this section when splitting work across pull requests. +These PR phases align with the playbook phases in the `meta-onboarding` skill (assessment → navigation → self-test/smoke → bug repro/SRE → verify/activate). Use the skill for step-by-step operator detail; use this section when splitting work across pull requests. ## What To Customize diff --git a/docs/framework.md b/docs/framework.md index f933d44..b58ea61 100644 --- a/docs/framework.md +++ b/docs/framework.md @@ -2,7 +2,7 @@ Harness engineering is the discipline of designing environments, repo knowledge, and feedback loops so an AI agent can execute work reliably. The work shifts from "write the code by hand" to "make the intended behavior legible, verifiable, and recoverable." -This repository is organized around three pillars: **Legibility** (navigation), **Autonomy** (verification and operational tooling within safe boundaries), and **Clarity** (executable plans and tickets once the core loop is proven). The six outcomes in `docs/outcomes.md` are the concrete proof model. +This repository is organized around three pillars: **Legibility** (navigation), **Autonomy** (verification and safe operational CLI access), and **Human-AI Interface** (the bidirectional channel between humans and the system, mediated by the agent — inbound for request refinement, outbound for operational signal interpretation). The six outcomes in `docs/outcomes.md` are the concrete proof model. ## Principle 1: Legibility — Make The Codebase AI-Legible @@ -53,26 +53,43 @@ Document three permission tiers in the root `AGENTS.md`: Never leave these boundaries implicit. -## Principle 3: Clarity — Plans And Tickets That Survive Contact With The Codebase +## Principle 3: Human-AI Interface — The Bidirectional Channel -Once the repo is legible and self-verifiable, debugging workflows and ticket refinement multiply the value of the rest of the system. +Legibility and Autonomy let the agent read and verify. The Human-AI Interface pillar is about the agent being a *channel* between humans and the system — in both directions. A codebase can be perfectly legible and fully self-verifying and still fail its people if vague requests arrive unchallenged or if production pain never surfaces back to the decision-makers. -### What Clarity Requires +### What The Interface Requires -Clarity compounds **after** the core outcomes in `docs/outcomes.md` are in place. It is not a substitute for proving `Self-Test`, `Bug Reproduction`, or `SRE Investigation`; use the evidence paths those outcomes establish for tests, repros, and operational signals. +The Interface pillar compounds **after** Legibility and Autonomy are in place. Without `AGENTS.md` context or trustworthy tests/smoke paths, the agent cannot critique a request or interpret a signal with grounded confidence. -- reproduce-before-fix discipline for bugs (fixes tie back to evidence the repo can rerun) -- a workshop pattern for refining vague requests into executable tickets (`clarity--ticket-writer`) -- a habit of turning lessons learned into repo-local documentation or rules +**Inbound channel — human → system** (`interface-ticket-writer`) +- Refines vague requests into tickets an agent can one-shot +- Surfaces missing edge cases, assumptions, success criteria before work starts +- A workshop pattern, not an autocomplete -### Ticket quality matters +**Outbound channel — system → human** (`interface-sre-agent`) +- Reproduce-before-fix discipline for bugs (fixes tie back to evidence the repo can rerun) +- Reads logs, metrics, traces, CI, and cloud CLIs — surfaces ranked hypotheses with evidence +- Relies on `autonomy-sre-auditor` having first proven that the required CLIs work -Work tickets are part of the harness. A vague ticket produces vague output. The goal is not to ask more questions than necessary, but to ask the few questions that surface missing edge cases, assumptions, and success criteria. +### Why two channels + +A system where humans can critique intake but production signals never reach the user through the agent is half-wired. A system where the agent diagnoses alerts but no one is refining the resulting work into executable tickets is also half-wired. Code-mint keeps both channels visible because agent readiness is not only about code execution; it is also about interpretation at the boundaries where humans and systems meet. ## Outcome Map Outcome names, proof criteria, and primary skill mappings are defined in `docs/outcomes.md`. Track progress and evidence in `docs/onboarding-checklist.md`. `.agents/code-mint-status.json` provides a machine-readable index of outcome statuses for cross-repo scanning. +## Related AIDLC Practices + +AWS AI-DLC is a useful external reference, but code-mint does not implement or vendor its full lifecycle. Two ideas are adopted directly because they improve audit quality without changing code-mint's outcome model: + +| Practice | How code-mint uses it | +|---|---| +| Adaptive depth | Auditors can run at `quick`, `standard`, or `deep` depth depending on repo age, risk, and recency of prior evidence. | +| Calibration | Audit reports name confidence, what was not checked, and what would raise confidence. | + +Workspace heritage (`Greenfield`, `Brownfield`, `Legacy`) is also used during onboarding as a lightweight calibration aid. AIDLC construction workflows, opt-in extension systems, and operations-phase artifacts are intentionally not part of this repository. + ## Cross-Cutting Standards These standards keep the repo legible as agent throughput increases. diff --git a/docs/onboarding-checklist.md b/docs/onboarding-checklist.md index 3784b95..40a75cc 100644 --- a/docs/onboarding-checklist.md +++ b/docs/onboarding-checklist.md @@ -124,12 +124,12 @@ The agent can inspect logs, metrics, traces, CI, or infra evidence. | Outcome | Skills To Reach It | |---|---| -| `Validate Current State` | `meta--onboarding` plus all applicable auditor skills | -| `Navigate` | `legibility--auditor`, `legibility--enhancer` | -| `Self-Test` | `autonomy--test-readiness-auditor`, `autonomy--test-readiness-creator` | -| `Smoke Path` | `autonomy--env-auditor`, `autonomy--env-creator`, `autonomy--runtime-auditor`, `autonomy--runtime-creator` | -| `Bug Reproduction` | `autonomy--sre-agent`, `autonomy--test-readiness-*` | -| `SRE Investigation` | `autonomy--sre-auditor`, `autonomy--sre-agent` | +| `Validate Current State` | `meta-onboarding` plus all applicable auditor skills | +| `Navigate` | `legibility-auditor`, `legibility-enhancer` | +| `Self-Test` | `autonomy-testing-auditor`, `autonomy-testing-creator` | +| `Smoke Path` | `autonomy-env-auditor`, `autonomy-env-creator`, `autonomy-staging-auditor`, `autonomy-staging-creator` | +| `Bug Reproduction` | `interface-sre-agent`, `autonomy-testing-*` | +| `SRE Investigation` | `autonomy-sre-auditor`, `interface-sre-agent` | ## Return-Visit Questions diff --git a/docs/outcomes.md b/docs/outcomes.md index 9e4bf6b..f64b475 100644 --- a/docs/outcomes.md +++ b/docs/outcomes.md @@ -6,22 +6,22 @@ Code-mint is most useful when the user can see a small number of concrete capabi | Outcome | What It Means | Proof Of Completion | Primary Skills | |---|---|---|---| -| `Validate Current State` | The agent can assess the repo as it exists today instead of guessing. | All applicable baseline audit outputs are recorded, and a concise summary captures what is working, blocked, risky, and next to prove. | `meta--onboarding`, applicable auditor skills | -| `Navigate` | The agent can explain the repo structure, identify the right module for a sample task, and justify where work should happen. | Durable in-repo guidance plus a grounded repo explanation or sample task walkthrough that shows the map is actually usable. | `legibility--auditor`, `legibility--enhancer` | -| `Self-Test` | The agent can run the smallest relevant automated check for a real module or behavior and trust the result. | An exact targeted test command or test target, the scope it covers, and a trustworthy pass/fail signal are captured in the checklist. | `autonomy--test-readiness-auditor`, `autonomy--test-readiness-creator` | -| `Smoke Path` | The agent can execute one safe, non-destructive runtime confidence check. | A documented smoke path with prerequisites, exact steps, stop conditions, and a concrete success signal such as a response, log line, or health check. | `autonomy--env-auditor`, `autonomy--env-creator`, `autonomy--runtime-auditor`, `autonomy--runtime-creator` | -| `Bug Reproduction` | The agent can turn a real reported issue into a reproducible failing case before proposing a fix. | A failing test, script, or deterministic reproduction recipe tied to the reported issue and runnable by another person or agent. | `autonomy--sre-agent`, `autonomy--test-readiness-*` | -| `SRE Investigation` | The agent can inspect logs, metrics, traces, CI, or infra context and produce a ranked hypothesis. | A short investigation log captures the evidence sources used, observed signals, ranked hypothesis, and next actions, or records why the outcome is `N/A`. | `autonomy--sre-auditor`, `autonomy--sre-agent` | +| `Validate Current State` | The agent can assess the repo as it exists today instead of guessing. | All applicable baseline audit outputs are recorded, and a concise summary captures what is working, blocked, risky, and next to prove. | `meta-onboarding`, applicable auditor skills | +| `Navigate` | The agent can explain the repo structure, identify the right module for a sample task, and justify where work should happen. | Durable in-repo guidance plus a grounded repo explanation or sample task walkthrough that shows the map is actually usable. | `legibility-auditor`, `legibility-enhancer` | +| `Self-Test` | The agent can run the smallest relevant automated check for a real module or behavior and trust the result. | An exact targeted test command or test target, the scope it covers, and a trustworthy pass/fail signal are captured in the checklist. | `autonomy-testing-auditor`, `autonomy-testing-creator` | +| `Smoke Path` | The agent can execute one safe, non-destructive runtime confidence check. | A documented smoke path with prerequisites, exact steps, stop conditions, and a concrete success signal such as a response, log line, or health check. | `autonomy-env-auditor`, `autonomy-env-creator`, `autonomy-staging-auditor`, `autonomy-staging-creator` | +| `Bug Reproduction` | The agent can turn a real reported issue into a reproducible failing case before proposing a fix. | A failing test, script, or deterministic reproduction recipe tied to the reported issue and runnable by another person or agent. | `interface-sre-agent`, `autonomy-testing-*` | +| `SRE Investigation` | The agent can inspect logs, metrics, traces, CI, or infra context and produce a ranked hypothesis. | A short investigation log captures the evidence sources used, observed signals, ranked hypothesis, and next actions, or records why the outcome is `N/A`. | `autonomy-sre-auditor`, `interface-sre-agent` | ## Why These Outcomes These outcomes map to three pillars: 1. **Legibility** — durable guidance so an agent can navigate intentionally. -2. **Autonomy** — trustworthy tests, safe runtime checks, and where applicable operational tooling (see `docs/framework.md` for what “autonomy” does and does not promise). -3. **Clarity** — after the core outcomes are in place, collaborative plans and tickets precise enough to execute. +2. **Autonomy** — trustworthy tests, safe runtime checks, and where applicable operational CLI access (see `docs/framework.md` for what “autonomy” does and does not promise). +3. **Human-AI Interface** — the bidirectional channel between humans and the system, mediated by the agent. Inbound: `interface-ticket-writer` refines vague requests into executable work. Outbound: `interface-sre-agent` interprets operational signals and surfaces them back to humans. -`clarity--ticket-writer` should be activated after the core onboarding outcomes are in place. Once the repo is legible and verifiable, better ticket writing compounds the rest of the system. +Interface skills are activated after the core onboarding outcomes are in place. Once the repo is legible and verifiable, better ticket refinement and signal interpretation compound the rest of the system. ## Evidence Model diff --git a/docs/skill-development.md b/docs/skill-development.md index a2371b2..3343f30 100644 --- a/docs/skill-development.md +++ b/docs/skill-development.md @@ -21,25 +21,25 @@ Skills are stored in `.agents/skills/` and automatically discovered by compliant ## Naming Convention -Skills in this repository use a category prefix with double-hyphen separator: +Skills in this repository use a category prefix with single-hyphen kebab case: ``` -{category}--{skill-name} +{category}-{skill-name} ``` **Categories:** | Prefix | Purpose | |---|---| -| `meta--` | Onboarding and skill-library management: creating, evaluating, and maintaining skills (aligned with `AGENTS.md`). | -| `autonomy--` | Skills that increase the agent's ability to operate independently. | -| `legibility--` | Skills that make the codebase understandable to agents. | -| `clarity--` | Skills for collaborative planning and executable tickets once core onboarding is in place. | +| `meta-` | Onboarding and skill-library management: creating, evaluating, and maintaining skills (aligned with `AGENTS.md`). | +| `autonomy-` | Skills that increase the agent's ability to operate independently (env, testing, staging runtime, SRE tool access). | +| `legibility-` | Skills that make the codebase understandable to agents. | +| `interface-` | Human-AI Interface — the bidirectional channel between humans and the system. Inbound: request refinement (ticket writing). Outbound: operational signal interpretation (SRE agent). | **Rules:** -- Lowercase letters, numbers, and hyphens only +- Lowercase letters, numbers, and hyphens only (single-hyphen kebab-case) - Max 64 characters -- The `--` separator must appear exactly once (between category and skill name) +- Exactly one hyphen separates the category prefix from the skill name; additional hyphens within the skill name itself are allowed (e.g. `autonomy-env-auditor`, `interface-ticket-writer`) --- @@ -49,7 +49,7 @@ Every skill requires YAML frontmatter followed by markdown instructions. ```markdown --- -name: category--skill-name +name: category-skill-name description: Brief description of what this skill does. Use when [trigger scenarios]. Do not use when [negative examples]. --- @@ -114,7 +114,7 @@ The context window is shared with conversation history, code, and other skills. - SKILL.md should be under 500 lines. - Move detailed reference material to `references/` files (loaded only when needed). - Keep references one level deep: `SKILL.md` links into `references/`; avoid chains where one reference file links to another. Deeply nested references may be partially read. -- **Exception:** A skill may link to another skill’s `references/` file when one canonical guide should stay in a single place (for example `autonomy--runtime-creator` pointing at `autonomy--runtime-auditor/references/smoke-test-guide.md`). Prefer one home for shared content to avoid drift. +- **Exception:** A skill may link to another skill’s `references/` file when one canonical guide should stay in a single place (for example `autonomy-staging-creator` pointing at `autonomy-staging-auditor/references/smoke-test-guide.md`). Prefer one home for shared content to avoid drift. ### Progressive Disclosure @@ -183,12 +183,12 @@ The reports directory itself should stay in version control, but generated repor | Auditor | Creator | |---|---| -| `autonomy--env-auditor` | `autonomy--env-creator` | -| `autonomy--runtime-auditor` | `autonomy--runtime-creator` | -| `autonomy--test-readiness-auditor` | `autonomy--test-readiness-creator` | -| `legibility--auditor` | `legibility--enhancer` | +| `autonomy-env-auditor` | `autonomy-env-creator` | +| `autonomy-staging-auditor` | `autonomy-staging-creator` | +| `autonomy-testing-auditor` | `autonomy-testing-creator` | +| `legibility-auditor` | `legibility-enhancer` | -`autonomy--sre-auditor` is intentionally not paired with a creator. Its remediation path routes to `autonomy--sre-agent`, an operational investigation tool rather than a remediation workflow. The auditor verifies tooling access; the agent uses that access to investigate real issues. +`autonomy-sre-auditor` is intentionally not paired with a creator. Its remediation path routes to `interface-sre-agent`, an operational investigation tool rather than a remediation workflow. The auditor verifies tooling access; the agent uses that access to investigate real issues. ### Report Format @@ -229,10 +229,11 @@ Every onboarded repository contains a committed `.agents/code-mint-status.json` ```json { - "code_mint": "1.0", + "code_mint": "1.1", "scope": ".", "onboarded_at": null, "last_validated": null, + "heritage": null, "outcomes": { "validate_current_state": { "status": "Not Started", "date": null }, "navigate": { "status": "Not Started", "date": null }, @@ -256,7 +257,7 @@ Whenever a skill updates `docs/onboarding-checklist.md`, also update `.agents/co **`Proven` means "last proven with recorded evidence"**, not a live guarantee. If the codebase drifts after proof, the fingerprint does not automatically invalidate. Use `last_validated` and periodic re-audits to detect staleness. -The `meta--onboarding` skill owns the lifecycle fields: `onboarded_at` is set when Phase 1 completes, and `last_validated` is set when Phase 5 verification runs. +The `meta-onboarding` skill owns the lifecycle fields: `onboarded_at` is set when Phase 1 completes, and `last_validated` is set when Phase 5 verification runs. ### Scoping @@ -264,11 +265,11 @@ The file lives at `.agents/code-mint-status.json` **relative to the onboarding s ### Create If Missing -`meta--onboarding` initializes the file during its Prepare Directories step. When a skill runs **standalone** (outside the onboarding playbook) and `.agents/code-mint-status.json` does not exist, the skill should create it from the template before updating. Set `scope` to `.` for repo-root or the appropriate path for scoped onboarding. +`meta-onboarding` initializes the file during its Prepare Directories step. When a skill runs **standalone** (outside the onboarding playbook) and `.agents/code-mint-status.json` does not exist, the skill should create it from the template before updating. Set `scope` to `.` for repo-root or the appropriate path for scoped onboarding. ### Parallel Writes -When multiple skills run in parallel (for example Phase 1 auditors), do not have each skill update the JSON individually. Concurrent writes to a single JSON file lose data. Instead, defer fingerprint updates to a single step after all parallel skills complete. `meta--onboarding` handles this in its "After Phase 1" step. +When multiple skills run in parallel (for example Phase 1 auditors), do not have each skill update the JSON individually. Concurrent writes to a single JSON file lose data. Instead, defer fingerprint updates to a single step after all parallel skills complete. `meta-onboarding` handles this in its "After Phase 1" step. ### Cross-Repo Scanning diff --git a/docs/skills-status.md b/docs/skills-status.md index 1082fc8..bf83adb 100644 --- a/docs/skills-status.md +++ b/docs/skills-status.md @@ -21,15 +21,15 @@ This status vocabulary is intentionally different from `docs/onboarding-checklis | Skill | Category | Supports Outcome | Status | Last Run | Notes | |---|---|---|---|---|---| -| `meta--onboarding` | Meta | `Validate Current State` | Not Started | — | Records the baseline audits and the summary of what is working, blocked, risky, and next to prove. | -| `legibility--auditor` | Legibility | `Navigate` | Not Started | — | Assesses repo navigability and identifies where durable guidance is missing. | -| `legibility--enhancer` | Legibility | `Navigate` | Not Started | — | Creates durable `AGENTS.md` guidance that can answer sample task-routing questions. | -| `autonomy--env-auditor` | Autonomy | `Smoke Path` | Not Started | — | Confirms env loading is safe and understandable before runtime proof. | -| `autonomy--env-creator` | Autonomy | `Smoke Path` | Not Started | — | Remediates env gaps that block a documented smoke path. | -| `autonomy--runtime-auditor` | Autonomy | `Smoke Path` | Not Started | — | Assesses install, startup, and smoke-path readiness, including success signals. | -| `autonomy--runtime-creator` | Autonomy | `Smoke Path` | Not Started | — | Builds the runtime path and smoke-check support with clear prerequisites and steps. | -| `autonomy--test-readiness-auditor` | Autonomy | `Self-Test` | Not Started | — | Baselines whether the repo has a smallest relevant automated check the agent can trust. | -| `autonomy--test-readiness-creator` | Autonomy | `Self-Test` and `Bug Reproduction` | Not Started | — | Improves targeted tests and regression coverage so exact checks and repros are runnable. | -| `autonomy--sre-auditor` | Autonomy | `SRE Investigation` | Not Started | — | Checks whether operational tooling is reachable before investigation proof begins. | -| `autonomy--sre-agent` | Autonomy | `Bug Reproduction` and `SRE Investigation` | Not Started | — | Produces deterministic repros and evidence-backed investigation notes with ranked hypotheses and next actions. | -| `clarity--ticket-writer` | Clarity | Post-onboarding activation | Not Started | — | Refines vague requests once the repo is legible and verifiable. | +| `meta-onboarding` | Meta | `Validate Current State` | Not Started | — | Records the baseline audits and the summary of what is working, blocked, risky, and next to prove. | +| `legibility-auditor` | Legibility | `Navigate` | Not Started | — | Assesses repo navigability and identifies where durable guidance is missing. | +| `legibility-enhancer` | Legibility | `Navigate` | Not Started | — | Creates durable `AGENTS.md` guidance that can answer sample task-routing questions. | +| `autonomy-env-auditor` | Autonomy | `Smoke Path` | Not Started | — | Confirms env loading is safe and understandable before runtime proof. | +| `autonomy-env-creator` | Autonomy | `Smoke Path` | Not Started | — | Remediates env gaps that block a documented smoke path. | +| `autonomy-staging-auditor` | Autonomy | `Smoke Path` | Not Started | — | Assesses install, startup, and smoke-path readiness, including success signals. | +| `autonomy-staging-creator` | Autonomy | `Smoke Path` | Not Started | — | Builds the runtime path and smoke-check support with clear prerequisites and steps. | +| `autonomy-testing-auditor` | Autonomy | `Self-Test` | Not Started | — | Baselines whether the repo has a smallest relevant automated check the agent can trust. | +| `autonomy-testing-creator` | Autonomy | `Self-Test` and `Bug Reproduction` | Not Started | — | Improves targeted tests and regression coverage so exact checks and repros are runnable. | +| `autonomy-sre-auditor` | Autonomy | `SRE Investigation` | Not Started | — | Checks whether operational tooling is reachable before investigation proof begins. | +| `interface-sre-agent` | Interface | `Bug Reproduction` and `SRE Investigation` | Not Started | — | Produces deterministic repros and evidence-backed investigation notes with ranked hypotheses and next actions. Outbound channel: system → human. | +| `interface-ticket-writer` | Interface | Post-onboarding activation | Not Started | — | Refines vague requests once the repo is legible and verifiable. Inbound channel: human → system. |