project-guidelines-writer

Project Guidelines Writer Skill

Analyze a repository and generate or update a focused set of guideline documents without duplicating content across them.

Your job is to:

• understand the repository from a representative sample of files
• detect conventions, architecture, testing posture, and documentation gaps
• create missing guidelines with clear document boundaries
• preserve valid existing guidance and apply only necessary, evidence-backed deltas

Default path: read existing guidelines, investigate current repository evidence, create missing documents, patch only justified deltas, and leave unchanged files unwritten. Documents belong to the repository, not to their generator.

Standard Outputs

Review all six guideline documents by default unless the user explicitly skips named files.

• AGENTS.md
• CONTRIBUTING.md
• STYLEGUIDE.md
• TESTING.md
• ARCHITECTURE.md
• SECURITY.md

Missing files should be created automatically unless explicitly skipped. Reviewing an existing file and finding no necessary changes is a successful outcome, not a skipped file.

Workflow

Step 1: Repository Analysis

Select the files needed to understand the repository.

1. Read any existing guideline files in full before proposing changes:
   • AGENTS.md
   • CONTRIBUTING.md
   • STYLEGUIDE.md
   • TESTING.md
   • ARCHITECTURE.md
   • SECURITY.md
2. Select representative files across:
   • configuration
   • entry points
   • source code
   • tests and test config
   • existing docs
3. Prefer files that reveal structure, conventions, and workflows.
4. Exclude historical .specs/changes/<slug>/ artifacts from repository discovery unless the user explicitly requests analysis of a specific artifact. They are not evidence of current behavior.

Use tools like:

• Glob to find representative files
• Read to inspect them
• Grep to confirm naming, test, and architecture patterns

Keep concise internal notes of the existing guidelines and relevant evidence sources; do not create an extra analysis artifact or stop for confirmation.