diff --git a/README.md b/README.md index 3777bf0..50f8f38 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# πŸ›‘οΈ Code Quality Skills +# πŸ›‘οΈ Code Verification, Cleaning & Planning Skills -> **A modular collection of AI sub-skills for verifying, cleaning, auditing, and securing code.** Install only the focused capability your task needs, or install the optional bundle for the complete workflow. +> **Reusable AI skills for project planning, code 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) @@ -48,28 +48,34 @@ Code Quality Skills separates code-quality work into small, composable sub-skill Install the smallest sub-skill that covers the task. For example, install **Clean Code** by itself: +#### Code Verification & Cleaning + ```bash npx skills add abozezo-dev/Code-Quality-Skill/clean-code ``` -Install any other individual sub-skill as needed: +#### Project Planning ```bash -# Automated builds, tests, linting, and formatting -npx skills add abozezo-dev/Code-Quality-Skill/code-verification +npx skills add abozezo-dev/Code-Quality-Skill/project-planning +``` -# Browser and DevTools runtime checks -npx skills add abozezo-dev/Code-Quality-Skill/runtime-auditing +### Quick Start -# Security-focused code review -npx skills add abozezo-dev/Code-Quality-Skill/security-review -``` +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/` -Or install the optional all-in-one bundle for the complete code-quality workflow: +--- -```bash -npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill -``` +## πŸ”— Skills.sh Listing + +View these skills on skills.sh: + +- [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. --- @@ -78,14 +84,8 @@ npx skills add abozezo-dev/Code-Quality-Skill/code-verify-and-clean-skill ```text Code-Quality-Skill/ β”œβ”€β”€ skills/ -β”‚ β”œβ”€β”€ clean-code/ -β”‚ β”‚ └── SKILL.md # Cleanup, deduplication, and modularity -β”‚ β”œβ”€β”€ code-verification/ -β”‚ β”‚ └── SKILL.md # Builds, tests, linting, and formatting -β”‚ β”œβ”€β”€ runtime-auditing/ -β”‚ β”‚ └── SKILL.md # Browser and DevTools validation -β”‚ β”œβ”€β”€ security-review/ -β”‚ β”‚ └── SKILL.md # Security-focused review +β”‚ β”œβ”€β”€ project-planning/ +β”‚ β”‚ └── SKILL.md # Planning-only skill specification β”‚ └── 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 d74a7b8..888ca20 100644 --- a/skills.sh.json +++ b/skills.sh.json @@ -2,6 +2,13 @@ "$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.", diff --git a/skills/project-planning/SKILL.md b/skills/project-planning/SKILL.md new file mode 100644 index 0000000..e0aef29 --- /dev/null +++ b/skills/project-planning/SKILL.md @@ -0,0 +1,150 @@ +--- +name: project-planning +description: | + Turns a requested change into an implementation-ready plan by clarifying requirements, + documenting assumptions, assessing risks and dependencies, sequencing milestones, and + defining verifiable acceptance criteria. Use before implementation when scope, behavior, + constraints, or delivery steps need to be agreed. +allowed-tools: + - Read + - Grep + - Glob + - Bash + - WebFetch +--- + +# Project Planning Skill + +Create a shared, implementation-ready plan before changing application code. This skill is +planning-only: gather evidence, clarify the requested outcome, and obtain agreement (or enough +specificity to proceed) before handing work to an implementation workflow. + +## When to Use This Skill + +- A request has unclear scope, users, behavior, success measures, or constraints. +- A feature, migration, integration, refactor, or rollout needs coordinated execution. +- A team needs an ordered plan that another agent can implement without rediscovering decisions. +- Risks, dependencies, trade-offs, or acceptance criteria need explicit treatment. + +## Planning Boundary + +- **Do not modify application code, configuration, infrastructure, tests, or production data.** +- Do not start implementation, run destructive migrations, or make speculative fixes while planning. +- Read-only repository inspection and non-mutating discovery commands are allowed when they reduce + uncertainty. +- Planning artifacts may be drafted only when requested or when the surrounding workflow permits + them; they must describe proposed work, not implement it. +- If requirements remain material and unresolved, ask targeted questions and clearly mark the plan + as pending agreement rather than guessing. + +## Workflow + +### 1. Establish the Planning Context + +1. Restate the requested outcome in one or two sentences. +2. Inspect relevant existing documentation, architecture, interfaces, and conventions using + read-only methods. +3. Record the current state, the desired state, affected users or systems, and explicit + out-of-scope items. +4. Separate known facts from assumptions and open questions. + +### 2. Ask Targeted Questions + +Ask only questions whose answers change scope, design, sequencing, cost, risk, or acceptance. +Prefer a short, prioritized set over a broad questionnaire. Cover gaps such as: + +- **Outcome:** What user or business problem must be solved, and how will success be measured? +- **Behavior:** What are the primary flows, edge cases, failure behavior, and non-goals? +- **Constraints:** What compatibility, performance, accessibility, security, privacy, budget, or + deadline constraints apply? +- **Ownership:** Who approves decisions, supplies content or credentials, and operates the result? +- **Delivery:** Is there a required rollout, migration, feature flag, monitoring, or rollback plan? + +For each question, state why it matters. If an answer is unavailable, propose a bounded default +assumption and label it for confirmation. + +### 3. Record Assumptions and Decisions + +Maintain an assumptions and decisions log with: + +| Item | Type | Rationale | Owner / source | Status | +| --- | --- | --- | --- | --- | +| Example: existing authentication is reused | Assumption | avoids a new identity flow | requester | needs confirmation | + +Mark every item as **confirmed**, **proposed**, or **open**. Never present a proposed assumption +as an agreed requirement. Identify which open items block planning or implementation. + +### 4. Identify Dependencies and Risks + +List dependencies that affect sequencing or delivery, including external services, APIs, data, +teams, approvals, environments, licenses, and release windows. For each material risk, capture: + +| Risk | Likelihood | Impact | Early signal | Mitigation | Contingency | Owner | +| --- | --- | --- | --- | --- | --- | --- | + +Prioritize risks that could invalidate the approach, delay a milestone, compromise safety, or +require a decision before implementation. Convert unresolved high-impact risks into explicit +decision gates. + +### 5. Break Work into Ordered Milestones + +Create small, outcome-oriented milestones in dependency order. Each milestone must state: + +1. **Goal and scope** β€” the observable outcome and included/excluded work. +2. **Prerequisites** β€” decisions, inputs, or prior milestones required to begin. +3. **Implementation approach** β€” the proposed components, interfaces, data changes, and validation + strategy at a level sufficient for an implementer to act. +4. **Deliverables and owner** β€” concrete outputs and responsible party. +5. **Acceptance criteria** β€” objective conditions proving the milestone is complete. +6. **Risks and rollback considerations** β€” relevant mitigations, release safeguards, and recovery + needs. + +Sequence discovery and decision gates before dependent build work. Call out parallelizable work +only when dependencies genuinely permit it. + +### 6. Produce the Implementation-Ready Plan + +Deliver a plan with the following structure: + +```markdown +# Plan + +## Objective +## Scope and Non-Goals +## Current-State Findings +## Requirements +## Open Questions and Assumptions +## Dependencies +## Risks and Mitigations +## Milestones +### Milestone 1 β€” +- Goal and scope: +- Prerequisites: +- Proposed approach: +- Deliverables and owner: +- Acceptance criteria: +- Risks / rollback: + +## Validation and Release Approach +## Decision Gates and Approval Needed +``` + +Make acceptance criteria observable and testable. Prefer statements such as β€œan authorized user +can complete X and receives Y,” β€œthe migration can be rolled back without data loss,” or β€œthe +defined latency target is met under the agreed workload,” rather than β€œworks correctly.” + +### 7. Confirm Readiness Before Handoff + +Before implementation, verify that: + +- Requirements and non-goals are sufficiently specific. +- Material assumptions are confirmed or explicitly approved as defaults. +- Dependencies have owners and a feasible order. +- High-impact risks have mitigations or decision gates. +- Every milestone has measurable acceptance criteria. +- The requester has agreed to the plan, or the documented evidence establishes that the plan is + sufficiently specified for implementation under the applicable workflow. + +If any condition fails, keep the work in planning, state the blocker, and ask the next targeted +question. Hand off only the agreed or sufficiently specified plan; implementation belongs to a +separate workflow.