Skip to content

chore: README + CONTRIBUTING.md + issue templates #7

Description

@randomm

What

Discoverability and onboarding. Three small docs.

README.md (~80-120 lines)

  1. Title + CI badge (added by issue chore: GitHub repo settings + CI workflow #5)
  2. One-paragraph description: Git worktree management plugin for the Pi agent harness. Provides safe create/list/remove of worktrees for parallel agent sessions, with guardrails against the data-loss patterns common in agentic workflows.
  3. Status: 0.1.0 — in development
  4. Install: pi install npm:@randomm/pi-worktree (once published) or manual copy to ~/.pi/agent/extensions/
  5. Configuration: settings.json snippet if applicable
  6. Usage: slash commands once feat: slash command handlers — /start, /research, /plan, /work in TypeScript #3 ships (/worktree create, /worktree list, /worktree remove)
  7. Safety guarantees: reference the footguns we explicitly guard against (branch-already-checked-out, dirty-remove, prune-before-delete, detached-HEAD, locked-leftover)
  8. License: Apache 2.0 — see LICENSE

CONTRIBUTING.md

  • Setup: bun install
  • Pre-push gates: bunx biome check . && bunx tsc --noEmit && bun test
  • Commit format: Conventional Commits with issue scope (e.g. feat(feat: worktree plugin #2):, chore(chore: GitHub repo settings + CI workflow #5):)
  • PR rules: include Fixes #N in PR body (not title); pass --base main to gh pr create
  • Reference AGENTS.md for the full agent-driven workflow

.github/ISSUE_TEMPLATE/

  • bug_report.md
  • feature_request.md
  • chore.md

Use the same template shapes pi-permissions evolved: title prefix, scope, why, acceptance criteria, out-of-scope, link to AGENTS.md if relevant.

Why

Readme is the front door. CONTRIBUTING tells humans how to send patches. Issue templates keep future issues at the quality bar pi-permissions reached only after several rounds of editing.

Acceptance criteria

  • README.md present with all 8 sections
  • CONTRIBUTING.md present with setup, gates, commit/PR rules
  • Three issue templates under .github/ISSUE_TEMPLATE/
  • License section in README says Apache 2.0 and links to LICENSE
  • No outdated MIT references anywhere

Out of scope

  • Detailed API docs (those live in JSDoc on exported types)
  • Tutorial / example projects
  • Changelog (defer until 1.0)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions