From 92455d62d9533501985c90b5eb1cf852918f013f Mon Sep 17 00:00:00 2001 From: abozezo-dev Date: Fri, 17 Jul 2026 23:05:02 +0300 Subject: [PATCH] Add four-stage execution workflow skill --- README.md | 53 +++++++++++----- skills.sh.json | 23 +++---- skills/code-execution-skill/SKILL.md | 93 ++++++++++++++++++++++++++++ 3 files changed, 142 insertions(+), 27 deletions(-) create mode 100644 skills/code-execution-skill/SKILL.md diff --git a/README.md b/README.md index 72c2041..70074e0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# πŸ›‘οΈ Code Verification & Cleaning Skill +# πŸ›‘οΈ Code Execution, Verification & Cleaning Skills -> **A reusable AI skill for code verification, cleanup, runtime auditing, and security-focused review, organized under `skills/code-verify-and-clean-skill/` for skills.sh discovery.** +> **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,6 +10,7 @@ ## πŸ“‹ Table of Contents - [Purpose](#-purpose) +- [Four-Stage Workflow](#-four-stage-workflow) - [Features](#-features) - [Getting Started](#-getting-started) - [Skills.sh Listing](#-skillssh-listing) @@ -23,7 +24,7 @@ ## 🎯 Purpose -This skill empowers AI agents to: +These skills guide AI agents through an explicit delivery workflow and empower them to: - βœ… **Verify code correctness** - Ensure logic works as intended - 🧹 **Remove dead code & duplication** - Keep codebases lean and maintainable @@ -34,6 +35,28 @@ This skill empowers AI agents to: --- +## 🧭 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 | Feature | Description | @@ -51,14 +74,18 @@ This skill empowers AI agents to: ### Installation ```bash +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 --- @@ -66,19 +93,11 @@ npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill View this skill 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) -The repository page is customized with [`skills.sh.json`](skills.sh.json), and the skill files live under [`skills/code-verify-and-clean-skill/`](skills/code-verify-and-clean-skill/) for a clean skills.sh-compatible layout. - ---- - -## πŸ”— Skills.sh Listing - -View this skill on skills.sh: - -- [Code Verification & Cleaning Skill](https://skills.sh/abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill) +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. -The repository page is customized with [`skills.sh.json`](skills.sh.json), which groups this skill under **Code Quality** for easier discovery. --- @@ -87,6 +106,8 @@ The repository page is customized with [`skills.sh.json`](skills.sh.json), which ``` Code-Quality-Skill/ β”œβ”€β”€ skills/ +β”‚ β”œβ”€β”€ code-execution-skill/ +β”‚ β”‚ └── SKILL.md # Four-stage delivery workflow β”‚ └── code-verify-and-clean-skill/ β”‚ β”œβ”€β”€ assets/ β”‚ β”‚ β”œβ”€β”€ report-template.md # Post-modification report template diff --git a/skills.sh.json b/skills.sh.json index 66be6f0..ca6bbf5 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -1,13 +1,14 @@ { - "$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-verify-and-clean-skill" - ] - } - ] + "$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