Project Kickoff Foundation

繁體中文 · Installation · Compatibility · Testing

project-kickoff-foundation is a reusable Agent Skill for turning early project decisions into a small, coherent foundation before implementation begins. It guides an AI coding agent and its human collaborator through product purpose, technical choices, boundaries, domain language, architecture, state and data flow, error handling, verification, review, and public-readiness decisions.

The skill grew out of practical notes, recurring questions, and lessons gathered across previous software projects. It packages those observations as prompts, templates, readiness gates, and checks—not as a universal methodology.

The core workflow at a glance. Conditional profiles add proportionate evidence where a project needs it; for example, multi-screen or high-risk user-facing work activates the Experience / UI Architecture gate described below.

Positioning

Project Kickoff Foundation sits one layer before the usual feature-specification workflow.

Many agent workflows start from brainstorming, grilling, or spec refinement. They are useful once there is already a feature or project direction to shape. PKF focuses on the earlier foundation layer: the project assumptions that should be explicit before implementation begins.

It treats the foundation as a decision ledger across product purpose, tech stack, privacy boundaries, domain language, naming conventions, architecture layers, state and data flow, error handling, verification commands, review/HITL workflow, public-readiness posture, UI/UX baseline, and proportionate Experience/UI Architecture readiness for user-facing work.

Each area is marked as Confirmed, Proposed, Open, or Not applicable, then checked through readiness gates: Concept, Feasibility, Foundation, conditional Experience / UI Architecture, and Implementation.

PKF is not a replacement for brainstorming or specification workflows. It gives those workflows a clearer base by making upstream project decisions visible, reviewable, and reusable.

The problem

New projects often begin coding while product intent, privacy boundaries, vocabulary, dependency direction, error behavior, and acceptance evidence still live as assumptions. Agents can then produce internally consistent code for a foundation nobody actually agreed to. This skill makes those decisions visible, labels their status, and stops before implementation when material blockers remain.

What it produces

The workflow creates or refreshes four core project-owned documents:

• AGENTS.md — concise operating instructions for contributors and agents
• CONTEXT.md — current purpose, scope, status, and open decisions
• docs/project-foundation.md — durable product and engineering decisions
• docs/design/ui-ux-design-system-v0.1.md — a versioned interface baseline, or an explicit headless baseline

For multi-screen, high-risk, or experience-heavy user-facing products, it also requires docs/design/ui-ux-architecture-v0.1.md. Headless projects and simple utilities keep the UI/UX work compact and do not get forced into the same documentation depth.

It also assesses concept, feasibility, foundation, Experience/UI Architecture when applicable, and implementation readiness. Higher-risk profiles add relevant questions for sensitive data, AI providers, reliability, native/filesystem access, local-first behavior, open source, migration, multi-tenancy, and user-facing experience architecture.

Readiness gates

Each applicable gate is reported as Ready, Conditionally ready, or Not ready; the Experience / UI Architecture gate may be Not applicable for headless and sufficiently simple projects. A gate is a decision aid, not a certification.

30-second quick start

Clone this repository, then copy the canonical skill directory into your agent's supported skill location.

Codex, project scope:

mkdir -p .agents/skills
cp -R /path/to/project-kickoff-foundation/skills/project-kickoff-foundation .agents/skills/

Claude Code, project scope:

mkdir -p .claude/skills
cp -R /path/to/project-kickoff-foundation/skills/project-kickoff-foundation .claude/skills/

Then ask the agent to run $project-kickoff-foundation in Codex or /project-kickoff-foundation in Claude Code. Windows PowerShell, user-scope installation, updates, verification, and uninstall instructions are in docs/installation.md.

Example

Input:

Establish a foundation for a Python 3.9+ CLI that creates deterministic SHA-256 manifests, never follows symlinks, and never overwrites without an explicit flag.

Expected output shape:

AGENTS.md
CONTEXT.md
docs/project-foundation.md
docs/design/ui-ux-design-system-v0.1.md

Concept: Ready
Feasibility: Conditionally ready
Foundation: Conditionally ready
Implementation: Not ready
Open: manifest byte format, overwrite flag, race behavior, platform matrix

The agent records the open decisions and verification contract; it does not implement the CLI unless separately asked.

Compatibility snapshot

See docs/compatibility.md and the linked evidence before relying on a version-specific claim.

Design principles

• Evidence before assumptions
• Explicit decision status: Confirmed, Proposed, Open, or Not applicable
• Proportionate depth based on project risk
• One authoritative home for each kind of context
• Public-safe examples and privacy-aware diagnostics
• Human approval for material, irreversible, destructive, or privacy-sensitive choices
• Honest compatibility claims backed by recorded validation

See docs/design-principles.md for the reasoning behind the workflow.

Repository layout

skills/project-kickoff-foundation/   Canonical portable skill package
docs/                                Public foundation and supporting guides
evals/                               Forward-test cases, raw fixtures, rubrics, and results
scripts/                             Repository-level validation
tests/                               Automated validator tests

The installable package is intentionally compact. Detailed templates live under its references/ directory and are loaded only when needed.

Validation

python -m unittest discover -s tests -v
python scripts/validate_repository.py .
python skills/project-kickoff-foundation/scripts/validate_foundation.py .

Compatibility is tiered as Validated, Specification-compatible, or Documented, not behaviorally tested. See docs/compatibility.md for the current matrix and exact meaning.

Limitations and non-goals

• The skill does not replace product discovery, delivery planning, threat modeling, legal review, or domain expertise.
• Readiness and validator results are not security, accessibility, privacy, or regulatory certification.
• Other models may read the package, but identical discovery, tool permissions, and behavior are not promised.
• The workflow does not resolve material human decisions or authorize destructive actions.
• The skill establishes a foundation; it does not implement product features unless that work is separately requested.

Contributing and security

Contributions are welcome when they keep the core workflow portable and evidence-driven. Read CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md before opening a change or reporting a vulnerability.

Author

Created and maintained by Kevin Yu-chang Tu
Polatouche.K · @kevintu2007 · LinkedIn

Acknowledgements

The portable package follows the open Agent Skills specification. Harness behavior is checked against the official Codex and Claude Code documentation. Community governance uses the Contributor Covenant.

License

Licensed under the MIT License.