ptp-artifact-contract

Defines the compact artifact schema governing all ptp planning documents.

Updated Jun 8, 2026
One-click install
npx skills add https://github.com/AlmogMaayan/ptp --skill ptp-artifact-contract-almogmaayan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ptp-artifact-contract
Source: https://github.com/AlmogMaayan/ptp/tree/main/skills/ptp-artifact-contract
Command: npx skills add https://github.com/AlmogMaayan/ptp --skill ptp-artifact-contract-almogmaayan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Planning artifacts in an AI-driven change pipeline tend to grow without bound, duplicating information and inflating review cost. This Skill establishes a single normative contract that fixes what each artifact owns, what it must not contain, and its word budget, so every writer and reader in the ptp pipeline works from the same rules. ## Core Features & Use Cases - Ownership table with budgets: Assigns each artifact (brainstorm.md, proposal.md, spec deltas, design.md, tasks.md, effort.md, prd.md, analysis.md) an exclusive scope and a hard or soft word budget backed by config keys. - Shape and policy rules: Enforces one-line effort.md, conditional design.md, build-state declarations in proposals, full MODIFIED delta reproduction, and a current-state-only update policy with no history sections. - Contract versioning: Distinguishes ptp-compact changes from legacy spec-driven changes via .openspec.yaml so old changes are interpreted under their original rules. - Use Case: A planner drafting a change that cannot fit the 400-word proposal budget returns NEEDS SPLIT instead of silently exceeding the limit, keeping review effort bounded. ## Quick Start Ask the AI to check whether the proposal.md and tasks.md in the current openspec change comply with the ptp compact artifact contract.

Frequently Asked Questions about ptp-artifact-contract

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the ptp compact artifact contract?▼

It is the normative schema governing every planning artifact in the ptp pipeline. It assigns each file an exclusive ownership scope, a word budget, and shape rules so artifacts stay compact and non-duplicative.

How do word budgets work for proposal and spec files?▼

Keyed budgets like artifact.maxProposalWords (400 words) are hard acceptance criteria; exceeding one is a defect fixed only by removing text or splitting the change. Soft budgets like brainstorm.md require a written budget-exception marker instead.

When is design.md required in a ptp change?▼

design.md is created only for cross-cutting changes, new architectural patterns, new external dependencies, significant data-model changes, security or migration complexity, or pre-coding ambiguity. It is absent otherwise and never an empty stub.

What happens when a change cannot fit its word budget?▼

An unmeetable keyed budget is a decomposition signal, not an exception. The planner returns NEEDS SPLIT and writes no more, treating the overrun as evidence the change should be divided.

Does the contract apply to older spec-driven changes?▼

No. Changes without .openspec.yaml or with schema spec-driven are legacy and interpreted under the pre-existing contract with TLDR.md and mandatory design.md. Readers tolerate them and nothing rewrites them.