Add project-planning skill and register it in skills.sh.json; update README

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

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.",

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
+# <Initiative> Plan
+
+## Objective
+## Scope and Non-Goals
+## Current-State Findings
+## Requirements
+## Open Questions and Assumptions
+## Dependencies
+## Risks and Mitigations
+## Milestones
+### Milestone 1 — <name>
+- 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.