firstp1ck/pi-coding-agent-forge/project-readme

Project README

Create or assess a useful project entry point from repository evidence. Adapt the bundled templates to the project's readers and local rules rather than treating them as mandatory section checklists. Offer companion documents when evidence supports them, and ask the user before creating either file. This skill is guidance, not a runtime guard, and loading it does not install, enable, publish, or modify anything by itself.

When to Use

Use this skill for a repository-level request to:

• create a missing project README;
• update, restructure, or harmonize an existing project README;
• audit or review a project README against repository evidence and documentation policy; or
• create separately approved TECHNICAL.md and DEVELOPMENT.md companions as part of the README task.

Do not use it for:

• general copywriting, release notes, blog posts, or arbitrary Markdown cleanup;
• writing API references, contributor guides, security policies, or package metadata as the primary task;
• changing implementation, packaging, publication, installation, or runtime configuration;
• rewriting many repositories or sibling projects without explicit per-destination scope;
• reviewing code quality when the project README is not the requested artifact.

Should trigger

• “Create the top-level README for this application from the repository contents.”
• “Update this library README with a verified quick start and public documentation links.”
• “Review our project README for unsupported claims and misplaced contributor details.”
• “Harmonize this repository README with its local documentation rules.”

Should not trigger

• “Write an API endpoint reference for this service.”
• “Fix the implementation and add tests.”
• “Draft release notes for the next version.”
• “Reformat every Markdown file in the organization.”

Ambiguous requests

A request such as “improve the docs” does not establish the artifact or write scope. Determine whether the user means the project README; otherwise route to the documentation workflow matching the actual artifact. A request to “document this package” may need a user-facing project README, an API reference, contributor documentation, or several separately scoped documents. Do not silently widen it.

Invocation Design

• Invocation mode: model-invoked after explicit package enablement.
• Leading concept: evidence-backed project README.
• Route narrowly to create, update, review, restructure, or harmonize a repository's primary README. Companion creation is subordinate to that task, not a reason to route standalone technical or contributor-guide requests here.
• Creation mode and update mode are write-capable. Review mode is read-only unless the user separately asks for edits.
• Enabling this skill later is a separate lifecycle action; package creation does not authorize installation, enablement, linking, or publication.

Inputs and Assumptions

Establish before drafting:

• the target repository and exact README path;
• whether the request is create, update, review, or harmonize;
• the intended readers and the project's actual type and maturity;
• repository-local instructions, documentation policy, and existing security, license, contributor, API, and technical documents;
• evidence for purpose, capabilities, requirements, commands, configuration, compatibility, support, license, and safety claims;
• authorized write scope and whether an existing user-authored README may be changed; and
• existing companion paths, substantive content for each proposed companion, and the user's separate creation decision for each missing file.

Treat repository-local policy as authoritative over this generic skill and template. Search from the target README's directory toward the repository root for applicable instruction files and inspect linked documentation conventions. When local rules conflict, follow the most specific applicable rule unless a higher-priority user instruction says otherwise. Record material adaptations in the result; do not weaken safety or privacy requirements silently.

Evidence and Audience Rules

Evidence first

Inspect relevant evidence before writing claims. Typical sources include the existing README, manifests, lockfiles, executable help, user-visible configuration, release metadata, license and security files, documentation indexes, verified assets, and implementation only where it establishes observable behavior.

• Trace every substantive command, feature, requirement, platform, compatibility, configuration, status, support, badge, and license claim to repository evidence.
• Prefer a verified narrow statement over an attractive broad claim.
• Never invent commands, badges, screenshots, compatibility, license text, performance results, roadmap commitments, links, or features.
• Do not copy credentials, private paths, demo passwords, personal data, or secret-like values into the README.
• If evidence is missing, conflicting, or stale, state the gap in the review or handoff and ask a focused question. Do not ship unresolved template placeholders as facts.
• Preserve essential safety, privacy, destructive-install, privilege, data-loss, and compatibility warnings before the step where readers encounter the risk.

Classify the primary audience

Choose one profile from evidence about the project's normal reader, not merely its implementation language.

User-oriented applies to applications, desktop or web products, CLI/TUI tools, setup or configuration repositories, and installable packages whose reader primarily wants to choose, install, configure, use, update, recover, or safely remove the result.

A user-oriented README must not contain development or implementation information. Prohibited inline content includes API calls or endpoints, request/response examples, schemas, architecture, technology stack, repository or source layout, internal algorithms, test commands or fixtures, benchmarks, contributor setup, source-build instructions, packaging or publication internals, and release-maintenance procedures. Link to an existing TECHNICAL.md, DEVELOPMENT.md, CONTRIBUTING.md, API reference, wiki, or generated help instead of summarizing that material inline.

Developer/library-oriented applies to libraries, SDKs, APIs, frameworks, reusable modules, and repositories whose normal reader integrates or extends code. Its README may include the public integration surface: installation, one minimal working code example, supported runtimes, public API or documentation links, compatibility, verification, and concise technical orientation. Keep internal algorithms, exhaustive architecture, source maps, fixtures, benchmarks, publication internals, and detailed contributor setup in dedicated documentation.

If evidence supports both audiences, identify the primary reader and give that reader the direct path; link the secondary reader to a dedicated destination. If classification remains genuinely unclear and changes what the README may contain, ask before drafting the disputed sections.

Companion document consent and layers

A README request does not authorize creating companion files. Use these distinct documentation layers:

• README.md is the starting point for purpose, capabilities, installation, first use, and essential safety warnings. Apply the selected audience profile and repository-local rules.
• TECHNICAL.md is an advanced user reference for complete commands and options, user-editable settings, requirements, compatibility, user storage locations, privacy controls, updates, recovery, and troubleshooting. It must not contain endpoint catalogs, payloads, schemas, tool contracts, architecture, algorithms, source maps, contributor setup, tests, fixtures, benchmarks, or publication internals.
• DEVELOPMENT.md is the contributor guide for implementation, architecture, source layout, API/RPC and tool contracts, payloads, schemas, internal state, algorithms, local development, tests, fixtures, benchmarks, and repository maintenance or publication.

Before creating a missing companion file:

1. Inspect existing documents and substantive evidence. Explain what belongs in each proposed file and recommend against an empty or duplicate document.
2. Ask the user separately whether to create TECHNICAL.md and whether to create DEVELOPMENT.md, using the exact target paths. The two questions may be collected together, but each needs its own explicit answer. Offer either file, both files, or neither; approval for one does not approve the other.
3. Record each decision as approved, declined, or unanswered. A prior explicit approval naming the same file and creation scope can be recorded without asking again. Never infer consent from a README request, repository policy, a template link, silence, or the other file's approval. Declined or unanswered means do not create that file.
4. Reuse existing companions as link targets. Do not overwrite or edit an existing companion unless that change is separately within the authorized write scope. If a file unexpectedly exists at creation time, stop and ask rather than replacing it.
5. Read the matching companion template only for an approved, evidence-supported creation. Do not create empty documents. Create and verify the destination before removing relocated content from the README, and link only to destinations that actually exist.
6. In review-only mode, report recommended companion documents and missing destinations without creating or editing them. A suggested move is not approval.

If a companion is declined or unanswered, keep verified content reachable in its current location, omit links to missing files, and report blocked relocation. If this conflicts with local policy, request a decision rather than deleting content or claiming policy-compliant completion.

Portable Workflow

1. Preflight policy, mode, and scope

• Resolve the target path, applicable local rules, requested branch, audience, overwrite authority, and allowed destinations. Identify existing companions without assuming permission to create or edit them.
• In create mode, confirm that the target is absent or that replacement is explicitly authorized. In update mode, preserve user-authored material until it has been checked. In review mode, make no edits unless separately requested.
• Completion criterion: the operation, target, policy precedence, audience profile, and write boundary are explicit.

1. Build an evidence inventory

• Inspect the evidence sources relevant to user-visible claims and note each claim's source, conflicts, and gaps.
• Identify existing documents that should remain canonical for technical, contributor, security, support, and legal detail.
• Completion criterion: every planned substantive claim has evidence, and every unresolved claim is omitted or recorded as a question.

1. Plan the reader path

• Read references/PROJECT-README-TEMPLATE.md and references/SECTION-DECISIONS.md.
• Apply the companion document consent step before adding missing destinations to the write plan. For approved creations, read references/PROJECT-TECHNICAL-TEMPLATE.md or references/PROJECT-DEVELOPMENT-TEMPLATE.md as appropriate.
• Select only relevant sections. Lead with outcome and capabilities, then the fastest safe first success. Put configuration and warnings before their effects; finish with support and license information where evidence exists.
• For a prototype, archive, migration, or incomplete rewrite, place status and limitations near the top. Do not imply unfinished behavior exists.
• Completion criterion: the outline fits the audience, local policy, project maturity, and evidence without empty or ceremonial sections; each missing companion has a recorded creation decision and only approved destinations are in scope.