diff --git a/README.md b/README.md index 50f8f38..380cd75 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# πŸ›‘οΈ Code Verification, Cleaning & Planning Skills +# πŸ›‘οΈ Code Execution, Verification & Cleaning Skills -> **Reusable AI skills for project planning, code verification, cleanup, runtime auditing, and security-focused review.** +> **Reusable AI skills for a four-stage code workflowβ€”planning, execution/building, verification, and reviewβ€”plus verification, cleanup, runtime auditing, and security-focused review.** ![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Status](https://img.shields.io/badge/status-active-success.svg) @@ -10,8 +10,10 @@ ## πŸ“‹ Table of Contents - [Purpose](#-purpose) -- [Sub-skills](#-sub-skills) -- [Installation](#-installation) +- [Four-Stage Workflow](#-four-stage-workflow) +- [Features](#-features) +- [Getting Started](#-getting-started) +- [Skills.sh Listing](#-skillssh-listing) - [Repository Structure](#-repository-structure) - [Core Principles](#-core-principles) - [Workflow](#-workflow) @@ -22,7 +24,7 @@ ## 🎯 Purpose -Code Quality Skills separates code-quality work into small, composable sub-skills. Choose a targeted skill when you need one type of review, or use the all-in-one bundle when a change needs the entire verification-and-cleaning workflow. +These skills guide AI agents through an explicit delivery workflow and empower them to: | Need | Owning sub-skill | |------|------------------| @@ -34,7 +36,29 @@ Code Quality Skills separates code-quality work into small, composable sub-skill --- -## 🧩 Sub-skills +## 🧭 Four-Stage Workflow + +Use [`skills/code-execution-skill/`](skills/code-execution-skill/) to coordinate every change through these ordered stages. Each stage has a required input and produces the handoff artifact required by the next stage. + +| Stage | Input | Output / handoff | +| --- | --- | --- | +| **1. Planning** | Change request and repository context | **Approved plan** covering scope, approach, risks, acceptance criteria, and planned checks. | +| **2. Execution / Building** | Approved plan | **Implementation summary** recording completed work, changed files, build results, deviations, and known risks. | +| **3. Verification** | Implementation summary and changed code | **Verification results** with lint, test, runtime, security, and reporting evidence. | +| **4. Review** | Implementation summary and verification results | **Final review findings** with structural, security, and evidence-based disposition. | + +### Shared verification and review skill + +Both **verification** and **review** use the existing [`skills/code-verify-and-clean-skill/`](skills/code-verify-and-clean-skill/) skill. Do **not** move or rewrite that skill; it remains the shared source of truth. + +- **Verification** follows its linting, tests, runtime checks, security checks, and reporting workflow. Record the commands, outcomes, evidence, remaining risks, and proceed/return recommendation in the verification results. +- **Review** follows its structural-cleanup standards, security-review guidance, [review template](skills/code-verify-and-clean-skill/assets/review-template.md), and verification evidence requirements. Record blocking issues, follow-ups, residual risks, and final disposition in the final review findings. + +A change is complete only after all four artifacts are preserved: approved plan, implementation summary, verification results, and final review findings. + +--- + +## ✨ Features - **[Clean Code](skills/clean-code/SKILL.md)** β€” owns dead-code removal, duplicate-code reduction, simplification, and modularity improvements. - **[Code Verification](skills/code-verification/SKILL.md)** β€” owns compilation, tests, linting, formatting, and other automated quality gates. @@ -57,14 +81,18 @@ npx skills add abozezo-dev/Code-Quality-Skill/clean-code #### Project Planning ```bash -npx skills add abozezo-dev/Code-Quality-Skill/project-planning +npx skills add abozezo-dev/Code-Quality-Skill/code-execution-skill + +# Add the shared verification and review skill +npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill ``` ### Quick Start -1. Add the skill to your AI agent configuration -2. Run verification on your target codebase -3. Review the generated report templates in `skills/code-verify-and-clean-skill/assets/` +1. Add `code-execution-skill` and the shared `code-verify-and-clean-skill` to your AI agent configuration +2. Create and approve a plan, then implement and build the change +3. Use the existing verification-and-cleaning skill for verification and review +4. Preserve the four required handoff artifacts --- @@ -72,10 +100,12 @@ npx skills add abozezo-dev/Code-Quality-Skill/project-planning View these skills on skills.sh: +- [Code Execution Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-execution-skill) - [Code Verification & Cleaning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill) - [Project Planning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/project-planning) -The repository page is customized with [`skills.sh.json`](skills.sh.json), which groups the skills for easier discovery. Skill definitions live under [`skills/`](skills/) in a skills.sh-compatible layout. +The repository page is customized with [`skills.sh.json`](skills.sh.json), and both skills live under [`skills/`](skills/) for a clean skills.sh-compatible layout. + --- @@ -84,8 +114,8 @@ The repository page is customized with [`skills.sh.json`](skills.sh.json), which ```text Code-Quality-Skill/ β”œβ”€β”€ skills/ -β”‚ β”œβ”€β”€ project-planning/ -β”‚ β”‚ └── SKILL.md # Planning-only skill specification +β”‚ β”œβ”€β”€ code-execution-skill/ +β”‚ β”‚ └── SKILL.md # Four-stage delivery workflow β”‚ └── code-verify-and-clean-skill/ β”‚ β”œβ”€β”€ assets/ # Bundle report and review templates β”‚ β”œβ”€β”€ reference/ # Bundle workflow guides diff --git a/skills.sh.json b/skills.sh.json index 888ca20..ca6bbf5 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -1,22 +1,14 @@ { - "$schema": "https://skills.sh/schemas/skills.sh.schema.json", - "notGrouped": "bottom", - "groupings": [ - { - "title": "Project Planning", - "description": "Requirements clarification, milestone planning, and implementation-ready delivery plans.", - "skills": [ - "project-planning" - ] - }, - { - "title": "Code Quality", - "description": "Plan-driven implementation, React/Next.js guidance, verification, cleanup, runtime auditing, and security review skills.", - "skills": [ - "code-verify-and-clean-skill", - "execution", - "react-best-practices" - ] - } - ] + "$schema": "https://skills.sh/schemas/skills.sh.schema.json", + "notGrouped": "bottom", + "groupings": [ + { + "title": "Code Quality", + "description": "Code verification, cleanup, runtime auditing, and security review skills.", + "skills": [ + "code-execution-skill", + "code-verify-and-clean-skill" + ] + } + ] } diff --git a/skills/code-execution-skill/SKILL.md b/skills/code-execution-skill/SKILL.md new file mode 100644 index 0000000..ebc4fc2 --- /dev/null +++ b/skills/code-execution-skill/SKILL.md @@ -0,0 +1,93 @@ +--- +name: code-execution-skill +description: | + Guides implementation work through an explicit planning, execution/building, + verification, and review workflow with documented handoffs. Reuses the + existing code-verify-and-clean-skill for verification and review. + Use when: planning a code change, implementing an approved plan, building an + application, coordinating quality gates, or preparing a change for handoff. +allowed-tools: + - Read + - Write + - Grep + - Glob + - Bash + - WebFetch + - Browser +--- + +# Code Execution Skill + +Deliver code changes through four ordered stages: **planning**, **execution/building**, **verification**, and **review**. A stage may begin only when it receives the required handoff artifact from the preceding stage, and it must produce the artifact required by the next stage. + +## Shared Quality Skill + +Stages 3 and 4 both use the existing [`skills/code-verify-and-clean-skill/`](../code-verify-and-clean-skill/) skill. **Do not move, copy, rewrite, or otherwise modify that skill as part of this workflow.** Treat it as the shared source of truth for verification, cleanup, security, templates, and reporting. + +## Workflow and Handoffs + +| Stage | Required input | Required work | Required output / handoff | +| --- | --- | --- | --- | +| 1. Planning | Change request and relevant repository context | Define scope, affected files, implementation approach, risks, acceptance criteria, and commands/checks to run. Resolve open questions before implementation. | **Approved plan** | +| 2. Execution / Building | Approved plan | Implement only the approved scope, make focused changes, and run the applicable build or generation steps. Record files changed, decisions, and any deviations from the plan. | **Implementation summary** | +| 3. Verification | Implementation summary and changed code | Use `skills/code-verify-and-clean-skill/` to run its linting, tests, runtime checks, security checks, and reporting workflow. Capture commands, outcomes, failures, and remaining risks. | **Verification results** | +| 4. Review | Implementation summary and verification results | Use `skills/code-verify-and-clean-skill/` to assess structural-cleanup standards and security-review guidance, complete its review template, and confirm verification evidence is sufficient for the change. | **Final review findings** | + +## Stage 1 β€” Planning + +Create an approved plan before editing implementation files. It must include: + +- Goal and non-goals. +- Affected files/components and expected change sequence. +- Risks, dependencies, and rollback considerations. +- Clear acceptance criteria. +- Expected build, test, lint, runtime, and security checks. + +**Handoff:** The approved plan is the only authorization for execution/building. If scope changes materially, update and re-approve the plan before continuing. + +## Stage 2 β€” Execution / Building + +Implement the approved plan in small, coherent changes. Build or generate artifacts as appropriate for the repository, and keep implementation notes accurate. + +The implementation summary must state: + +- The approved-plan items completed and any approved deviations. +- Files changed and the purpose of each change. +- Build/generation commands run and their outcomes. +- Known limitations, deferred work, or risks to pass to verification. + +**Handoff:** Supply the implementation summary and changed code to verification. + +## Stage 3 β€” Verification + +Verification must use the existing [`skills/code-verify-and-clean-skill/`](../code-verify-and-clean-skill/) without moving or rewriting it. Follow that skill's established workflow for: + +1. **Linting and static checks** β€” run applicable formatters, linters, type checks, and compilation/build checks. +2. **Tests** β€” execute relevant unit, integration, and other repository-native test suites. +3. **Runtime checks** β€” when applicable, run the application and use its DevTools/browser guidance to inspect behavior, console output, and network requests. +4. **Security checks** β€” apply its security-verification guidance for input handling, exposure risks, dependencies, and other relevant attack surfaces. +5. **Reporting** β€” follow its reporting workflow and record findings and evidence using its supplied reporting assets where applicable. + +Verification results must include the exact commands/checks, pass/fail status, pertinent output or evidence, unresolved findings, and an explicit recommendation to proceed or return to execution/building. + +**Handoff:** Pass the verification results, together with the implementation summary, to review. Any blocking verification failure returns the change to Stage 2. + +## Stage 4 β€” Review + +Review must also use the existing [`skills/code-verify-and-clean-skill/`](../code-verify-and-clean-skill/) without moving or rewriting it. Review the implementation and verification evidence against that skill's: + +- **Structural-cleanup standards** for modularity, duplication, dead code, clarity, and maintainability. +- **Security-review guidance** for vulnerabilities, unsafe handling, secret exposure, and residual risk. +- **Review template** in `assets/review-template.md` to make findings consistent and actionable. +- **Verification evidence** from Stage 3, confirming that checks are relevant, complete, and sufficient for the claimed behavior. + +Final review findings must identify approved items, blocking issues, non-blocking follow-ups, residual risks, and the final disposition: approve, approve with follow-ups, or return to execution/building. + +## Completion Rule + +A change is complete only after final review findings have been produced and the final disposition is approval (with any follow-ups explicitly recorded). Preserve all four handoff artifacts with the change record: + +1. Approved plan +2. Implementation summary +3. Verification results +4. Final review findings