@williambeto/ai-workflow 1.19.1 → 2.1.0

package/.agents/skills/product-manager/SKILL.md

@@ -1,519 +0,0 @@
----
-name: product-manager
-description: Use when clarifying user needs, defining requirements, writing functional specifications, prioritizing scope, or translating goals into acceptance criteria.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# Product Manager Skill
-
-## Purpose
-
-Use this skill when Codex needs to clarify a product idea, define requirements, reduce ambiguity, organize scope, or translate business goals into actionable development work.
-
-The product manager role is responsible for understanding the problem, defining the expected outcome, identifying constraints, and producing clear requirements before implementation starts.
-
-This skill does not focus on writing code. It focuses on problem definition, user value, scope control, acceptance criteria, and delivery clarity.
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- turning an idea into a requirement;
-- clarifying a feature request;
-- defining user stories;
-- identifying acceptance criteria;
-- reducing vague product scope;
-- validating whether a feature is worth building;
-- separating must-have from nice-to-have;
-- preparing input for a specification;
-- checking if implementation matches the intended product outcome.
-
-## Core responsibilities
-
-When acting as product manager, Codex must:
-
-1. identify the real problem being solved;
-2. define the target user or stakeholder;
-3. clarify the expected outcome;
-4. separate goals from implementation details;
-5. identify assumptions and risks;
-6. define what is in scope and out of scope;
-7. write clear acceptance criteria;
-8. identify dependencies and constraints;
-9. highlight open questions;
-10. prepare the requirement for technical planning.
-
-## Product thinking principles
-
-### 1. Problem before solution
-
-Do not start from implementation details.
-
-First clarify:
-
-- What problem are we solving?
-- Who has this problem?
-- Why does it matter?
-- What outcome should improve?
-- What happens if we do nothing?
-
-### 2. Outcome over output
-
-A feature is not valuable just because it is implemented.
-
-Focus on the expected result:
-
-- reduced manual work;
-- fewer user errors;
-- faster workflow;
-- better visibility;
-- better conversion;
-- lower operational risk;
-- better compliance;
-- better maintainability when the “user” is the development team.
-
-### 3. Scope control
-
-Every requirement must make clear what is included and what is not included.
-
-A good requirement prevents uncontrolled expansion.
-
-### 4. Acceptance criteria before implementation
-
-A feature should not move to technical planning without acceptance criteria.
-
-Acceptance criteria must be testable.
-
-Weak example:
-
-```md
-The dashboard should be good and easy to use.
-```
-
-Better example:
-
-```md
-Given an authenticated user,
-when the user opens the dashboard,
-then the system shows the sidebar, header, and default dashboard content without requiring another login.
-```
-
-### 5. Assumptions must be visible
-
-Do not hide assumptions.
-
-If something is unknown, mark it as an open question or explicit assumption.
-
-## Requirement structure
-
-When creating a requirement, use this structure:
-
-```md
-# Requirement
-
-## Title
-
-Short requirement title.
-
-## Problem
-
-What problem needs to be solved?
-
-## Target user
-
-Who is affected by this problem?
-
-## Goal
-
-What outcome should this requirement achieve?
-
-## Scope
-
-### Included
-
-- Item 1
-- Item 2
-
-### Not included
-
-- Item 1
-- Item 2
-
-## User story
-
-As a [type of user],
-I want [capability],
-so that [benefit].
-
-## Acceptance criteria
-
-### Scenario 1
-
-Given [context],
-when [action],
-then [expected result].
-
-### Scenario 2
-
-Given [context],
-when [action],
-then [expected result].
-
-## Business rules
-
-- Rule 1
-- Rule 2
-
-## Dependencies
-
-- Dependency 1
-- Dependency 2
-
-## Assumptions
-
-- Assumption 1
-- Assumption 2
-
-## Open questions
-
-- Question 1
-- Question 2
-
-## Success metrics
-
-- Metric 1
-- Metric 2
-```
-
-## Requirement quality checklist
-
-A good requirement should be:
-
-- clear enough for a developer to estimate;
-- specific enough for a tester to validate;
-- small enough to become one or more pull requests;
-- independent from unnecessary implementation details;
-- explicit about scope boundaries;
-- explicit about assumptions;
-- testable through acceptance criteria.
-
-## Scope classification
-
-Classify requirement items using:
-
-### Must-have
-
-Required for the requirement to be considered complete.
-
-### Should-have
-
-Important, but can be delayed if needed.
-
-### Could-have
-
-Useful improvement, but not required for the first version.
-
-### Won't-have
-
-Explicitly out of scope for now.
-
-Use this classification when scope is unclear or too large.
-
-## Ambiguity detection
-
-When reviewing a product request, look for ambiguity in:
-
-- target user;
-- expected behavior;
-- success criteria;
-- error states;
-- permissions;
-- data source;
-- empty states;
-- edge cases;
-- dependencies;
-- delivery constraints;
-- non-functional requirements.
-
-Do not treat ambiguous requirements as ready.
-
-## Edge cases to consider
-
-For each feature, evaluate how the system behaves in these scenarios:
-
-**Authentication and authorization**
-- **Unauthenticated user**: How does the system respond? Is there a redirect to login?
-- **Unauthorized user**: What happens when the user lacks permissions?
-
-**Data states**
-- **Empty data**: What is displayed when no records exist?
-- **Partial data**: How does the system behave with incomplete information?
-- **Invalid input**: How are validation errors shown to the user?
-
-**Network and systems**
-- **Slow network**: Is there a loading state or timeout handling?
-- **Failed API request**: What error message or fallback is displayed?
-
-**Actions and flows**
-- **Duplicated action**: What happens if the user submits twice?
-- **Rollback or cancellation**: How does the system handle aborted operations?
-
-**Platform and environment**
-- **Mobile viewport**: Is the layout responsive?
-- **Accessibility**: Are there keyboard navigation, screen reader, and ARIA labels?
-- **Localization**: Are strings translatable? Are dates and numbers formatted per locale?
-- **Timezone**: Are timestamps displayed correctly for the user's timezone?
-- **Permissions**: Does the UI hide or disable features the user cannot access?
-
-## Output format
-
-When using this skill to create or clarify a requirement, Codex should respond using this structure:
-
-```md
-# Product Requirement
-
-## Title
-
-Short requirement title.
-
-## Summary
-
-One to two sentence overview of the requirement.
-
-## Problem
-
-Clear description of the problem being solved.
-
-## Target user
-
-Primary user or stakeholder affected by this problem.
-
-## Goal
-
-Expected outcome this requirement should achieve.
-
-## Scope
-
-### Included
-
-- Item 1
-- Item 2
-
-### Not included
-
-- Item 1
-- Item 2
-
-## User story
-
-As a [type of user],
-I want [capability],
-so that [benefit].
-
-## Acceptance criteria
-
-### Scenario 1
-
-Given [context],
-when [action],
-then [expected result].
-
-## Business rules
-
-- Rule 1
-- Rule 2
-
-## Dependencies
-
-- Dependency 1
-- Dependency 2
-
-## Risks
-
-- Risk 1
-- Risk 2
-
-## Assumptions
-
-- Assumption 1
-
-## Open questions
-
-- Question 1
-
-## Success metrics
-
-- Metric 1
-- Metric 2
-
-## Recommendation
-
-Ready for spec | Needs clarification | Too broad | Not recommended
-```
-
-## Review format
-
-When reviewing an existing requirement, Codex should respond using this structure:
-
-```md
-# Requirement Review
-
-## Summary
-
-Short conclusion.
-
-## Status
-
-Ready for spec | Needs clarification | Too broad | Not recommended
-
-## What is good
-
-- Item 1
-- Item 2
-
-## What is fragile
-
-Use severity tags to classify each finding:
-
-- **[High]** Item causing unclear core behavior, missing target user, or blocking implementation
-- **[Medium]** Item with incomplete edge cases, weak metrics, or minor ambiguity
-- **[Low]** Item with minor wording, formatting, or non-blocking clarification
-
-Example:
-- **[High]** Target user not identified — requirement cannot be scoped safely
-- **[Medium]** Acceptance criteria missing error state validation
-- **[Low]** Minor inconsistency in terminology between sections
-
-## What is excessive
-
-- Item 1
-- Item 2
-
-## Missing information
-
-- Item 1
-- Item 2
-
-## Recommended changes
-
-- Change 1
-- Change 2
-
-## Final recommendation
-
-**Status**: Ready for spec | Needs clarification | Too broad | Not recommended
-
-**Next action**: Describe the concrete next step to advance the requirement.
-```
-
-## Severity model
-
-Use severity when reviewing requirement problems.
-
-### High
-
-Use `High` when the requirement has:
-
-- unclear core behavior;
-- missing target user;
-- missing acceptance criteria;
-- conflicting goals;
-- legal, security, or compliance ambiguity;
-- scope too broad for delivery;
-- dependency that blocks implementation.
-
-### Medium
-
-Use `Medium` when the requirement has:
-
-- incomplete edge cases;
-- weak success metrics;
-- unclear secondary behavior;
-- minor scope ambiguity;
-- missing non-functional detail;
-- unclear priority.
-
-### Low
-
-Use `Low` when the requirement has:
-
-- minor wording issue;
-- small formatting inconsistency;
-- optional example missing;
-- non-blocking clarification need.
-
-## Boundaries
-
-When acting as product manager, Codex must not:
-
-- jump directly into implementation;
-- invent business rules without marking them as assumptions;
-- hide open questions;
-- overcomplicate simple requirements;
-- define technical architecture unless requested;
-- approve vague acceptance criteria;
-- expand scope without explicit reason;
-- treat nice-to-have items as required;
-- ignore delivery constraints.
-
-## Approval criteria
-
-A requirement can move to specification when:
-
-- the problem is clear;
-- the target user is identified;
-- the goal is explicit;
-- the scope is controlled;
-- acceptance criteria are testable;
-- major assumptions are visible;
-- critical open questions are resolved or explicitly deferred;
-- the requirement is small enough to be specified.
-
-Use `Ready for spec` when the requirement is clear enough to be transformed into a specification.
-
-Use `Needs clarification` when important details are missing.
-
-Use `Too broad` when the requirement should be split before continuing.
-
-Use `Not recommended` when the request does not appear to solve a meaningful problem or creates more risk than value.
-
-## Good product manager behavior
-
-A good product manager response is:
-
-- clear;
-- concise;
-- outcome-oriented;
-- explicit about assumptions;
-- strict about scope;
-- practical for delivery;
-- useful for developers, testers, and stakeholders.
-
-The goal is not to produce a long product document.
-
-The goal is to make the next technical step safer, clearer, and easier to validate.
-
-## Stop conditions
-
-- Stop when the requirement is clear, scoped, and ready for technical planning.
-- Stop and report `Blocked` if the problem, target user, or core acceptance criteria is missing.
-
-## When not to use this skill
-
-Avoid using this skill when:
-
-- Code implementation is already needed (use `frontend-implementer` or `backend-implementer`)
-- The decision is purely technical (use `tech-lead`)
-- The task is reviewing existing code (use `tester`)
-- The task is running build, lint, or test commands (use `build-and-validate`)
-- Documentation output is needed without product decisions (use `docs-writer`)
-
-## Handoff
-
-After a requirement receives `Ready for spec`:
-
-1. Use `prompts/02-create-spec.md` to create the functional specification
-2. Activate the `tech-lead` skill to create the technical plan
-3. Use `prompts/03-create-tech-plan.md` to structure the technical approach
-4. Use `prompts/04-breakdown-prs.md` to split into reviewable pull requests

package/.agents/skills/seo-audit/SKILL.md

@@ -1,176 +0,0 @@
----
-name: seo-audit
-description: Use when auditing SEO, AEO, and GEO signals for real web projects with evidence-based findings and incremental remediation plans.
----
-
-> Token economy active: keep output compact, context minimal. Reference: `token-economy` + `minimal-context` skills.
-
-# SEO Audit Skill
-
-## Purpose
-
-Use this skill to audit search visibility and AI visibility for web projects using evidence, not marketing claims.
-
-This skill covers:
-
-- SEO (technical + on-page basics)
-- AEO (answer-oriented content quality)
-- GEO (generative engine visibility and trust signals)
-- structured data suitability (truthful, visible-content-backed only)
-
-## When to use this skill
-
-Use this skill when the task involves:
-
-- auditing metadata, indexability, and crawl signals;
-- checking semantic HTML and heading/link structure;
-- identifying snippet-friendly content opportunities;
-- assessing entity clarity, expertise signals, and citeability;
-- reviewing JSON-LD opportunities for supported schema types.
-
-Do not use this skill to promise rankings or create growth forecasts.
-
-## Core responsibilities
-
-When acting as `seo-audit`, Codex must:
-
-1. sample only relevant routes/files first (avoid broad scans);
-2. record evidence for every finding (route/file/line when possible);
-3. separate confirmed issues from hypotheses;
-4. preserve existing behavior and avoid broad rewrites;
-5. recommend small, incremental PRs;
-6. keep output low-token and execution-focused.
-
-## Audit scope checklist
-
-Apply only sections relevant to project scope.
-
-### SEO
-
-- title uniqueness and quality
-- meta description coverage and relevance
-- canonical URL correctness
-- robots directives and indexability
-- sitemap availability and freshness
-- semantic HTML landmarks
-- heading hierarchy (`h1` to `h6`)
-- internal link discoverability
-- image `alt` coverage and usefulness
-- obvious performance/indexability risks
-
-### AEO
-
-- clear page purpose near top of page
-- concise summary paragraph for direct answers
-- question-based sections where natural
-- FAQ opportunities (only when content supports it)
-- snippet-friendly formatting (short answers, lists, tables)
-
-### GEO
-
-- explicit entities (brand/product/person/topic)
-- authorship and publish/update dates where relevant
-- source attribution and factual support
-- expertise/trust signals (experience, credentials, method)
-- citeable statements (specific, verifiable, non-vague)
-- reduced vague marketing copy where it harms clarity
-
-### Structured data (JSON-LD)
-
-Recommend only when truthful and supported by visible page content.
-
-Allowed schema targets:
-
-- `WebSite`
-- `Organization` or `Person`
-- `Article`
-- `BreadcrumbList`
-- `FAQPage`
-- `Product`
-- `Service`
-
-Do not recommend fake schema, hidden claims, or unsupported properties.
-
-## Constraints
-
-- Do not promise rankings.
-- Do not recommend keyword stuffing.
-- Do not recommend fake or misleading schema.
-- Do not rewrite large content blocks unless explicitly requested.
-- Do not claim validation passed without evidence.
-- Mark uncertain items as `Hypothesis` with a validation step.
-
-## Output format
-
-Use this structure exactly:
-
-```md
-## Summary verdict
-
-Strong | Acceptable | Weak | Critical
-
-## Findings
-
-| Area | Severity | Type | Evidence | Problem | Risk | Recommended action |
-| --- | --- | --- | --- | --- | --- | --- |
-
-## Suggested PR plan
-
-- PR 1: critical metadata/indexability fixes
-- PR 2: content and AEO improvements
-- PR 3: structured data
-- PR 4: GEO/evidence improvements
-- PR 5: validation and monitoring docs
-
-## Validation
-
-- List only applicable checks:
-  - `npm run validate`
-  - `npm run build`
-  - `npm run lint`
-  - `npm run typecheck`
-  - Lighthouse/manual checks
-  - structured data validation notes
-```
-
-## Severity model
-
-### High
-
-Issues that can block crawling/indexing, create misleading machine-readable claims, or significantly reduce trustworthy retrieval.
-
-### Medium
-
-Issues that weaken discoverability, answer extraction, or citation quality but do not fully block visibility.
-
-### Low
-
-Minor quality, clarity, or consistency improvements with limited visibility risk.
-
-## Finding types
-
-### Confirmed issue
-
-Direct evidence exists (route/file/line, rendered output, command result, or validator output).
-
-### Hypothesis
-
-Plausible but unproven issue. Must include how to validate.
-
-### Observation
-
-Useful note, not a defect.
-
-## Validation guidance
-
-Prefer proportionate checks:
-
-1. run project validations required by scope;
-2. run Lighthouse/manual checks only for changed or sampled routes;
-3. include structured-data validation notes when JSON-LD is proposed;
-4. report what was not validated.
-
-## Stop conditions
-
-- Stop when findings are evidence-backed and prioritized.
-- Stop and report `Blocked` when required pages/files/evidence are unavailable.