Skip to content

PRD.md

Latest commit

 

History

History
429 lines (322 loc) · 17.8 KB

PRD.md

File metadata and controls

429 lines (322 loc) · 17.8 KB
Raw

KISS — Product Requirements Document

Working expansion: Keep It Simple. Ship.
Status: Approved concept; ready for implementation planning
Primary targets: Claude Code, Codex, OpenCode, Pi
Format: Agent Skills SKILL.md

1. Product summary

KISS is a personal, agent-agnostic product-building system that moves work from idea to verified release with the least process necessary.

It combines the strongest ideas from Matt Pocock's Skills, gstack, and Superpowers while rejecting large role libraries, rigid ceremony, and duplicated workflows.

The default kiss skill assesses the request and invokes only the stages that add value. Every stage remains independently callable.

2. Problem

Existing agent-development systems are capable but broad. They often introduce:

  • Too many overlapping skills and personas.
  • Mandatory ceremony for small changes.
  • Long prompts that consume context and obscure the actual work.
  • Framework-specific assumptions.
  • Plans and documents that become larger than the product.

A solo builder needs the rigor of discovery, planning, implementation, and QA without carrying a virtual company around every task.

3. Product principles

  1. Less is more. Include a step only when skipping it creates meaningful risk.
  2. Keep it simple. Prefer the smallest design, dependency set, diff, and document that solves the problem.
  3. Process must justify itself. The workflow must never cost more than the work.
  4. Evidence over confidence. Never claim success without current verification.
  5. One source of truth. Avoid duplicated requirements, tasks, or status.
  6. Portable by default. Core behavior must not depend on one agent, model, issue tracker, or tool.
  7. Human judgment stays central. Agents may recommend; consequential product and release decisions remain visible to the user.

4. Goals

  • Support the complete product lifecycle: discovery, research, definition, planning, implementation, verification, and release.
  • Provide one adaptive entry point: kiss.
  • Allow every workflow stage to be invoked independently.
  • Work for web, mobile, desktop, backend, CLI, and other software products.
  • Store tasks locally in Markdown by default.
  • Support GitHub Issues as an optional task backend.
  • Produce concise, actionable artifacts.
  • Encourage simple architecture and small, reversible changes.
  • Work across Claude Code, Codex, OpenCode, and Pi using the open Agent Skills format.

5. Non-goals

  • Recreating a virtual executive or engineering organization.
  • Providing a skill for every framework, language, or vendor.
  • Replacing project-specific instructions or domain knowledge.
  • Requiring subagents, browser automation, MCP servers, or GitHub access.
  • Enforcing TDD where it provides no practical value, such as pure content or configuration changes.
  • Automatically deploying, publishing, merging, deleting, or spending money without clear authorization.

6. Users

Primary user

A solo technical product builder using AI agents across multiple projects and runtimes.

Core jobs

  • Turn a rough idea into a buildable product definition.
  • Research uncertain decisions without generating a literature review.
  • Convert approved scope into executable tasks.
  • Implement without scope drift or unnecessary abstraction.
  • Find defects before release.
  • Preserve enough state to continue work in another session or agent.

7. Skill set

Primary workflow

Skill Purpose Expected output
kiss Assess scope and orchestrate the minimum useful workflow Selected route, then completed work
discover Clarify the problem, user, constraints, success criteria, and uncertain assumptions Concise product brief and research findings when needed
define Convert an approved direction into a lean PRD or technical specification docs/kiss/prd.md
plan Break approved scope into small, ordered, verifiable tasks docs/kiss/tasks.md or optional GitHub Issues
build Implement tasks incrementally using repository conventions and suitable tests Working code and updated task state
verify Check requirement fidelity, correctness, UX, security, and regressions Findings, fixes when authorized, and verification evidence
ship Prepare and, when authorized, execute release work Clean release, release notes, deployment evidence

Supporting utilities

Skill Purpose Trigger
debug Reproduce, isolate, explain, fix, and regression-test unexpected behavior Bugs, failures, regressions, unexplained performance problems
simplify Remove unnecessary scope, code, abstractions, dependencies, or process Complexity is growing or a simpler solution may exist
handoff Preserve decisions, progress, blockers, and the next action Session, model, or agent transition

No additional skill belongs in version 1 unless it cannot be expressed cleanly through these ten.

The public callable IDs are kiss and the namespaced stage IDs kiss-discover, kiss-define, kiss-plan, kiss-build, kiss-verify, kiss-ship, kiss-debug, kiss-simplify, and kiss-handoff. Friendly prose may use the short stage labels.

8. Adaptive workflow

kiss must select one of three routes using observable risk and ambiguity, not task size alone.

Direct route

Use when the request is clear, localized, reversible, and covered by an existing validation path.

Default stages: build → verify

Examples: copy correction, narrow styling change, known dependency bump, small isolated bug with an obvious reproduction.

Standard route

Use when requirements need clarification, several components change, or implementation choices affect maintainability.

Default stages: discover → define → plan → build → verify

Examples: a new user-facing feature, meaningful workflow change, new integration, or cross-module refactor.

Extended route

Use when building a product from scratch or when the work has high uncertainty, external dependencies, security implications, migration risk, or a production release.

Default stages: discover with targeted research → define → plan → build → verify → ship

Routing rules

  • State the chosen route and reason in one sentence.
  • Ask only questions whose answers could change the result.
  • Skip research when repository evidence or stable knowledge is sufficient.
  • Permit the user to add, remove, or invoke any stage directly.
  • Reassess the route when new risk or scope appears.
  • Never restart a completed stage without a concrete reason.

9. Stage requirements

9.1 Discover

  • Inspect existing project context before proposing changes.
  • Identify the user, problem, desired outcome, constraints, exclusions, and success signal.
  • Separate facts, assumptions, and open decisions.
  • Ask one focused question at a time when clarification is needed.
  • Research only decision-relevant uncertainty.
  • Prefer primary and current sources for technical claims.
  • Present two or three materially different approaches when a real trade-off exists.
  • Recommend one approach and explain why.
  • Stop when further discovery would not change the decision.

9.2 Define

  • Produce the shortest specification that makes implementation unambiguous.
  • Cover scope, non-goals, user flows, requirements, constraints, acceptance criteria, and important failure states.
  • Add architecture or data-flow detail only when the implementation needs it.
  • Record consequential decisions once; reference them elsewhere.
  • Require user approval before implementation for standard and extended routes.

9.3 Plan

  • Create vertical, outcome-based tasks rather than layer-based busywork.
  • Give every task a clear result and verification method.
  • Record dependencies only when they truly block execution.
  • Keep local Markdown as the canonical default.
  • Create GitHub Issues only when requested or configured.
  • Avoid estimates, epics, labels, and project-management metadata unless they affect execution.

9.4 Build

  • Follow the approved PRD, task, and repository conventions.
  • Work in the smallest coherent increments.
  • Use tests before implementation for behavior changes when an automated test is practical.
  • Avoid speculative abstractions and unrelated refactors.
  • Preserve user changes and stop on ambiguous destructive operations.
  • Update task state after verification, not merely after editing.

9.5 Verify

  • Verify against requirements and acceptance criteria, not intuition.
  • Run the smallest relevant checks first, then the broader regression suite when warranted.
  • Review the final diff for correctness, simplicity, security, accessibility, and scope drift.
  • Exercise user-visible flows in a real runtime when tools permit.
  • Distinguish verified facts, unverified areas, and blockers.
  • Never report completion from stale or partial evidence.

9.6 Ship

  • Confirm the working tree, target, release contents, and required authorization.
  • Generate concise release notes from user-visible changes.
  • Run final verification against the exact release candidate.
  • Use repository-native release and deployment processes.
  • Report the released version or commit, destination, and evidence.
  • If deployment cannot be verified, say so plainly.

9.7 Debug

  • Reproduce the failure before changing implementation.
  • Reduce it to the smallest reliable case.
  • Gather evidence and form a falsifiable hypothesis.
  • Fix the cause, not the symptom.
  • Add a regression check when practical.

9.8 Simplify

  • Preserve required behavior while reducing concepts, branches, dependencies, files, or process.
  • Prefer deletion and consolidation over new abstraction.
  • Reject changes that merely move complexity or hide it behind indirection.
  • Verify behavior after simplification.

9.9 Handoff

  • Record the objective, current state, decisions, changed files, verification, blockers, and exact next action.
  • Link existing PRD and task files instead of duplicating them.
  • Exclude conversation history that does not affect future work.

10. Artifact contracts

Lean PRD

The default PRD contains only:

  1. Summary
  2. Problem
  3. Goals and non-goals
  4. Users or use cases
  5. Requirements
  6. Important design decisions
  7. Acceptance criteria
  8. Risks or open questions

Sections with no decision value should be omitted.

Task file

Each task contains:

  • Outcome
  • Relevant files or subsystem, when known
  • Dependencies, when real
  • Acceptance check
  • State: pending, active, blocked, or done

Only one task may be active unless parallel execution is explicitly supported and useful.

Handoff file

The handoff contains:

  • Objective
  • Current state
  • Decisions
  • Work completed
  • Verification performed
  • Blockers
  • Next action

11. Repository design

kiss/
├── README.md
├── LICENSE
├── skills/
│   ├── kiss/SKILL.md
│   ├── kiss-discover/SKILL.md
│   ├── kiss-define/
│   │   ├── SKILL.md
│   │   └── assets/prd-template.md
│   ├── kiss-plan/
│   │   ├── SKILL.md
│   │   └── assets/tasks-template.md
│   ├── kiss-build/SKILL.md
│   ├── kiss-verify/SKILL.md
│   ├── kiss-ship/SKILL.md
│   ├── kiss-debug/SKILL.md
│   ├── kiss-simplify/SKILL.md
│   └── kiss-handoff/
│       ├── SKILL.md
│       └── assets/handoff-template.md
└── tests/
    ├── routing/
    ├── behavior/
    └── fixtures/

Each skill must be self-contained. Cross-references use skill names rather than runtime-specific paths.

12. Portability

  • Use only fields supported by the Agent Skills specification.
  • Require name and description YAML frontmatter followed by Markdown instructions.
  • Keep skill names lowercase and hyphen-safe.
  • Avoid hard-coded tool names when a capability description is sufficient.
  • Describe fallbacks for missing browser, subagent, issue-tracker, and deployment capabilities.
  • Keep canonical skill sources under skills/.
  • Distribute through the skills.sh CLI from PGHQdev/KISS.
  • Use the CLI's canonical-copy and symlink installation model, with its copy fallback where symlinks are unavailable.
  • Test installation, update, and removal without reimplementing those lifecycle operations.
  • KISS never uses non-interactive installation by default.
  • Users must review and confirm detected destinations.
  • Existing same-ID skills may be replaced after confirmation.
  • Namespaced IDs reduce but do not eliminate collision risk.

12.1 Distribution

  • The canonical source is https://github.com/PGHQdev/KISS.
  • Install the latest stable release on every supported platform with npx skills add PGHQdev/KISS --global --skill "*".
  • Keep the default branch aligned with the latest stable release.
  • Tag immutable releases using Semantic Versioning, such as v1.0.0; prereleases do not become the default branch release.
  • Attach kiss-vX.Y.Z.tar.gz and SHA256SUMS to every release for auditing and manual or offline installation.
  • License the repository and all bundled skills under the MIT License.
  • Use the skills.sh CLI for listing, updating, removing, canonical storage, symlinking, and copy fallback.
  • Do not ship Claude Code or Codex plugin packages in version 1.
  • Support platforms where Node.js, npx, skills.sh, and the selected harness are supported. Validate the release on current macOS, Ubuntu, and Windows CI runners.

13. Context and writing limits

  • Keep the frequently loaded kiss/SKILL.md below 200 words where possible.
  • Keep every other SKILL.md below 500 words unless tests prove more guidance is necessary.
  • Put templates in assets/; add references only when a stage cannot remain clear without them.
  • Do not repeat general software-engineering knowledge.
  • Use imperative instructions and concrete output contracts.
  • Put triggering conditions in each skill's description.
  • Avoid motivational prose, personas, origin stories, and duplicated examples.

14. Testing strategy

Every skill must be developed and validated independently.

Routing evaluations

Test kiss against at least:

  • A trivial text or style change.
  • A localized bug.
  • A new cross-component feature.
  • A product from scratch.
  • A risky migration or security-sensitive change.
  • A direct request for one named stage.
  • A request that expands in scope during execution.

The route passes when it includes every risk-reducing stage and no stage without decision value.

Skill behavior evaluations

For each skill:

  1. Run representative prompts without the skill and record relevant failures.
  2. Write the minimum guidance needed to correct those failures.
  3. Run the same prompts with the skill.
  4. Add edge cases and pressure scenarios.
  5. Remove guidance that does not measurably affect behavior.

Cross-runtime validation

Run one direct, one standard, and one extended scenario on every primary target. Confirm:

  • Skill discovery works.
  • Direct invocation works.
  • Cross-skill references resolve.
  • Artifacts are written to the intended paths.
  • Missing optional capabilities degrade gracefully.

15. Success criteria

Version 1 is complete when:

  • All ten skills conform to the Agent Skills specification.
  • kiss reliably selects direct, standard, and extended routes in the routing suite.
  • Each stage works independently.
  • Trivial changes do not create a PRD or task file.
  • Standard and extended work cannot silently bypass required user approval.
  • Local Markdown task management works without external services.
  • GitHub Issues can be selected without changing the core planning workflow.
  • Verification reports include fresh command or runtime evidence.
  • Interactive installation through skills.sh shows all detected destinations; declining a same-ID replacement preserves the existing skill, while confirmation may replace it.
  • Update and removal work through skills.sh on macOS, Linux, and Windows test environments.
  • All skills pass baseline-versus-skilled behavior evaluations.

16. Version 1 exclusions

  • Multi-agent orchestration framework.
  • Persistent memory database.
  • Built-in browser or deployment engine.
  • Jira, Linear, Asana, or other task backends.
  • Framework-specific coding skills.
  • Design-system generation.
  • Analytics or telemetry.
  • Automatic self-updating.

17. Risks and mitigations

Risk Mitigation
kiss becomes a large meta-prompt Keep it as a short router; delegate procedures to stage skills
Skills activate too often Use narrow trigger descriptions and negative routing tests
Skills duplicate one another Give each skill one output and one lifecycle responsibility
Adaptive routing skips useful rigor Test ambiguous, risky, and expanding-scope scenarios
Workflow becomes dogmatic Make stage inclusion depend on observable risk and decision value
Portability drifts Keep canonical files specification-compliant and test every target
Documents become performative Enforce lean artifact contracts and omit empty sections

18. Implementation order

Build and validate one skill at a time:

  1. kiss-simplify
  2. kiss-discover
  3. kiss-define
  4. kiss-plan
  5. kiss-debug
  6. kiss-build
  7. kiss-verify
  8. kiss-ship
  9. kiss-handoff
  10. kiss
  11. Cross-runtime distribution and integration suite

Build kiss last so its routing reflects proven skill boundaries rather than speculative ones.

19. References