planager 0.1.1__py3-none-any.whl

planager/__init__.py

@@ -0,0 +1 @@
+"""planager — Feature plans for LLM-assisted development."""

planager/cli.py

@@ -0,0 +1,112 @@
+"""CLI entry point: `planager init` sets up a project for plan-based development."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from importlib.resources import files
+from pathlib import Path
+
+SNIPPET_MARKER = "<!-- planager:start -->"
+SNIPPET_END_MARKER = "<!-- planager:end -->"
+
+TEMPLATES = files("planager.templates")
+
+
+def get_template_path() -> Path:
+    """Resolve the templates directory to a filesystem path."""
+    return Path(str(TEMPLATES))
+
+
+def init_project(target: Path) -> list[str]:
+    """Install planager files into *target* project directory.
+
+    Returns a list of actions taken (for user feedback).
+    """
+    actions: list[str] = []
+    template_dir = get_template_path()
+
+    # 1. Create .plans/ directory
+    plans_dir = target / ".plans"
+    if not plans_dir.exists():
+        plans_dir.mkdir(parents=True)
+        actions.append("Created .plans/")
+    else:
+        actions.append(".plans/ already exists, skipped")
+
+    # 2. Copy skill files
+    skills_dir = target / ".claude" / "skills"
+    for skill_name in ("plan", "plan-status"):
+        skill_dest = skills_dir / skill_name / "SKILL.md"
+        skill_src = template_dir / skill_name / "SKILL.md"
+
+        if skill_dest.exists():
+            actions.append(f".claude/skills/{skill_name}/SKILL.md already exists, skipped")
+        else:
+            skill_dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(skill_src), str(skill_dest))
+            actions.append(f"Created .claude/skills/{skill_name}/SKILL.md")
+
+    # 3. Append CLAUDE.md snippet
+    claude_md = target / "CLAUDE.md"
+    snippet = (template_dir / "CLAUDE.md.snippet").read_text()
+    wrapped_snippet = f"{SNIPPET_MARKER}\n{snippet}{SNIPPET_END_MARKER}\n"
+
+    if claude_md.exists():
+        existing = claude_md.read_text()
+        if SNIPPET_MARKER in existing:
+            actions.append("CLAUDE.md already has planager snippet, skipped")
+        else:
+            with claude_md.open("a") as f:
+                f.write("\n" + wrapped_snippet)
+            actions.append("Appended planager snippet to CLAUDE.md")
+    else:
+        claude_md.write_text(wrapped_snippet)
+        actions.append("Created CLAUDE.md with planager snippet")
+
+    return actions
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="planager",
+        description="Feature plans for LLM-assisted development.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    init_parser = sub.add_parser(
+        "init",
+        help="Set up the current project for plan-based development.",
+    )
+    init_parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Project root directory (default: current directory).",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command is None:
+        parser.print_help()
+        return 1
+
+    if args.command == "init":
+        target = args.path.resolve()
+        if not target.is_dir():
+            print(f"Error: {target} is not a directory.", file=sys.stderr)
+            return 1
+
+        actions = init_project(target)
+        print(f"Initialized planager in {target}\n")
+        for action in actions:
+            print(f"  {action}")
+        print("\nDone. Start a Claude Code session and plans will work automatically.")
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

planager/templates/CLAUDE.md.snippet

@@ -0,0 +1,75 @@
+
+# Feature Plans
+
+This project uses **planager** for structured feature planning. Plans are
+markdown files in `.plans/` with phased steps and checkboxes.
+
+## Automatic behavior
+
+### On session start
+
+Check `.plans/` for any plans with `status: in-progress` or `status: blocked`.
+If any exist, briefly note them to the user (e.g. "There's an in-progress plan
+for <title>"). If the user's request clearly relates to one, read it and resume
+from the first unchecked step. Don't force it — if the user is asking about
+something unrelated, just mention the plan exists and move on.
+
+### When starting new feature work
+
+Before writing code for a non-trivial feature, create a plan:
+
+1. Ask the user for a brief description (if not already provided).
+2. Explore the codebase to understand what's involved.
+3. Draft a phased plan with concrete, checkable steps.
+4. Present the plan to the user for approval.
+5. Save the approved plan to `.plans/<feature-slug>.md`.
+6. Begin implementation from Phase 1.
+
+Skip planning for trivial tasks (single-file fixes, typos, config changes).
+Use judgment — if the work spans multiple files or sessions, it deserves a plan.
+
+### While working on a planned feature
+
+- Check off steps (`- [x]`) as they are completed.
+- Add notes to the `## Notes` section for decisions, blockers, or alternatives
+  considered.
+- Update the `updated` date in frontmatter.
+- Set `status: in-progress` when work begins (if still `planning`).
+- If blocked, set `status: blocked` and note the reason.
+
+### On completion
+
+- Set `status: done` in frontmatter.
+- Write a brief summary in `## Notes` of what was built.
+- Check off all remaining steps.
+
+## Plan format
+
+```markdown
+---
+feature: short-slug
+title: Human-Readable Title
+status: planning | in-progress | blocked | done
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+## Context
+
+What the feature is, why it matters, constraints, links to issues or docs.
+
+## Phase 1: <title>
+
+Brief description of this phase.
+
+- [ ] Step description
+- [ ] Step description
+
+## Phase 2: <title>
+
+- [ ] Step description
+
+## Notes
+
+Running log of decisions, blockers, things tried.
+```

planager/templates/plan/SKILL.md

@@ -0,0 +1,35 @@
+# /plan — Create or resume a feature plan
+
+When the user invokes `/plan`, follow this workflow.
+
+## If given a description (e.g. `/plan add dark mode support`)
+
+1. Choose a short slug from the description (e.g. `dark-mode`).
+2. Check if `.plans/<slug>.md` already exists.
+   - If it does and is `in-progress`, switch to the **resume** flow below.
+   - If it does and is `done`, tell the user and ask if they want a new plan.
+3. Explore the codebase to understand what the feature involves:
+   - Read relevant files, check existing patterns, identify what needs to change.
+4. Draft a phased plan with concrete steps. Each step should be small enough
+   to complete in one action (a file edit, a test run, etc.).
+5. Present the plan to the user. Ask for approval or adjustments.
+6. Save the approved plan to `.plans/<slug>.md` with `status: planning`.
+7. Ask the user if they want to begin implementation now.
+   - If yes, set `status: in-progress` and start from Phase 1, step 1.
+
+## If invoked without a description (e.g. just `/plan`)
+
+1. Glob `.plans/*.md` and read the frontmatter of each.
+2. List any `in-progress` or `blocked` plans.
+3. If there are in-progress plans, ask the user:
+   - Resume one of them? (default if there's only one)
+   - Or create a new plan?
+4. If creating new, ask for a brief description and follow the flow above.
+
+## Resume flow
+
+1. Read the full plan file.
+2. Summarize current status: which phases are done, what's next.
+3. Begin work from the first unchecked step.
+4. Follow the standard plan update behavior (check steps, add notes, update
+   frontmatter) as you work.

planager/templates/plan-status/SKILL.md

@@ -0,0 +1,22 @@
+# /plan-status — Show status of all feature plans
+
+When the user invokes `/plan-status`, do the following:
+
+1. Glob `.plans/*.md` to find all plan files.
+2. If no plans exist, say so and exit.
+3. For each plan file, read it and extract:
+   - `feature` and `title` from frontmatter
+   - `status` from frontmatter
+   - Checkbox counts: total `- [ ]` and `- [x]` lines per `## Phase N:` section
+   - Overall progress: completed steps / total steps
+4. Print a summary table, for example:
+
+```
+Feature          Status       Progress
+───────────────  ───────────  ────────────────
+auth             in-progress  Phase 2: 3/7
+dark-mode        planning     Phase 1: 0/4
+api-v2           done         5/5
+```
+
+5. If any plan is `blocked`, show the reason from the Notes section if available.

planager-0.1.1.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: planager
+Version: 0.1.1
+Summary: Feature plans for LLM-assisted development. One command sets up your project so coding agents automatically create, follow, and maintain structured plans.
+Project-URL: Repository, https://github.com/forest-d/planager
+Author: forest-d
+License-Expression: MIT
+Keywords: claude,codex,development,llm,planning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# planager
+
+Feature plans for LLM-assisted development.
+
+One command sets up your project so coding agents (Claude Code, Codex, etc.)
+automatically create, follow, and maintain structured feature plans across
+sessions.
+
+## Install
+
+```bash
+cd your-project
+uvx planager init
+```
+
+That's it. No runtime dependencies, no background processes. The command copies
+a few template files into your project and you're done.
+
+## What it does
+
+After `planager init`, your project gets:
+
+- **`.plans/`** — directory where feature plans live (markdown files).
+- **`.claude/skills/plan/`** — a `/plan` slash command for creating and resuming plans.
+- **`.claude/skills/plan-status/`** — a `/plan-status` slash command for checking progress.
+- **CLAUDE.md snippet** — instructions that make the agent automatically discover
+  and follow plans without you having to ask.
+
+## How it works
+
+Plans are markdown files with frontmatter, phased steps, and checkboxes:
+
+```markdown
+---
+feature: auth
+title: User Authentication
+status: in-progress
+created: 2026-04-18
+updated: 2026-04-18
+---
+
+## Context
+
+Implement email/password authentication with session management.
+
+## Phase 1: Database schema
+
+- [x] Create users table migration
+- [x] Add password hashing utility
+- [ ] Add session table migration
+
+## Phase 2: API endpoints
+
+- [ ] POST /login
+- [ ] POST /register
+
+## Notes
+
+Using bcrypt for hashing. Decided against JWT — sessions are simpler for now.
+```
+
+The CLAUDE.md snippet teaches the agent to:
+
+1. **Check for in-progress plans** at the start of each session.
+2. **Create plans** before starting non-trivial features.
+3. **Update plans** as work progresses (check off steps, add notes).
+4. **Mark plans done** when a feature is complete.
+
+No special tools or MCP servers — the agent reads and writes plain markdown files.
+
+## Slash commands
+
+### `/plan`
+
+Create a new feature plan or resume an existing one.
+
+- With a description: `/plan add dark mode support` — explores the codebase,
+  drafts a phased plan, asks for approval.
+- Without: `/plan` — lists in-progress plans and offers to resume or create new.
+
+### `/plan-status`
+
+Show progress across all plans:
+
+```
+Feature          Status       Progress
+───────────────  ───────────  ────────────────
+auth             in-progress  Phase 2: 3/7
+dark-mode        planning     Phase 1: 0/4
+api-v2           done         5/5
+```
+
+## Idempotent
+
+Running `uvx planager init` again is safe — it skips files that already exist
+and won't duplicate the CLAUDE.md snippet.
+
+## License
+
+MIT

planager-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+planager/__init__.py,sha256=epy7RGoiiClOFva8dyElWibyIU08Gg-yfLZa4uPhsQA,63
+planager/cli.py,sha256=YR6mSHleEA-W3zE3qt-fArBFlIbu332biGMc5j2K18g,3440
+planager/templates/CLAUDE.md.snippet,sha256=CitSzrtFmsinSA5czhct5tKBLM9GJtiHtZK07AysQgg,2131
+planager/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+planager/templates/plan/SKILL.md,sha256=thTGhlRWHXtcNqMQbAFhZfsJgdvSEI_25w9-0i3NDC0,1607
+planager/templates/plan-status/SKILL.md,sha256=tLq43-wYicmIdFy6dwtXOfIIlu4F-3NL9VTHSfUuB2o,868
+planager-0.1.1.dist-info/METADATA,sha256=AzRxt7hfdsuQO3lpKV2q-dEB0Qh7xpOUrNW4AowClsY,3222
+planager-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+planager-0.1.1.dist-info/entry_points.txt,sha256=RNKI-EOTSugD0VaOWu5AguWHdE_otCzdSNG0-vLW4dc,47
+planager-0.1.1.dist-info/RECORD,,

planager-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

planager-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+planager = planager.cli:main