Jose Gibson
← All Projects

Devlog CLI — Agent-Aware Project Manager

A Python CLI that acts as a shared state engine between a developer and their AI agents — tracking goals, blockers, and journey entries across projects with git-backed persistence and portfolio export.

PythonTyper + Rich (CLI and terminal UI)python-frontmatter (structured Markdown storage)Pydantic (schema validation)Git (automatic audit trail via commits)

Portfolio Highlights

  • →Built a Python CLI that acts as a shared state engine between a developer and AI agents, with git-backed persistence, per-project state isolation, and structured Pydantic data models.
  • →Designed a double-ledger architecture: a central Markdown index for long-term history and per-project AGENTS.md files for live agent working memory.
  • →Implemented a sanitized JSON export pipeline that strips internal entries and feeds a public portfolio frontend.

Stack

  • Python
  • Typer + Rich (CLI and terminal UI)
  • python-frontmatter (structured Markdown storage)
  • Pydantic (schema validation)
  • Git (automatic audit trail via commits)

What I Built

  • Double-ledger state engine: central index of project Markdown files + per-project AGENTS.md for live agent working memory.
  • Per-project .devlog.json for isolated goal/handoff state — no global session clobbering across terminals.
  • Pydantic-validated data model: Project, Hurdle, JourneyEntry with visibility (public/internal) and status fields.
  • YAML frontmatter migration across 26 project files for robust, queryable storage.
  • devlog export command: strips [INTERNAL] entries and outputs sanitized JSON for the portfolio frontend.
  • Goal deduplication: setting the same goal twice is a no-op in the journey log.
  • Commands: link, unlink, status, standup, goal, block, resolve, log, decide, decisions, handoff, reset, edit, list, show, export.

Key Decisions

  • Central index stays source of truth; AGENTS.md is a generated working copy. Keeps portfolio cards (archived/offline projects) working without requiring live repos.
  • Per-project state file (.devlog.json) instead of global session — multiple terminals in different projects can't clobber each other.
  • [INTERNAL] tag is parsed structurally at read-time (Pydantic visibility field), not as a brittle string prefix at write-time.
  • Git auto-commit on every write creates a queryable audit trail of the developer journey.

Development Timeline

  1. Build a CLI to bridge active development sessions and a long-term professional portfolio
  2. Implemented core commands: link, status, goal, hurdle, resolve, log, handoff
  3. Initial git-commit logic for non-repo paths
  4. Expand CLI with local state management (AGENTS.md)
  5. Implemented Double-Ledger State Engine: central index + local AGENTS.md for agent working memory
  6. Refactor devlog CLI for production standards: YAML Frontmatter, Pydantic validation, and Export engine
  7. Killed global session state; per-project .devlog.json now owns goal and handoff
  8. Added goal deduplication, devlog unlink, devlog edit commands
  9. Migrated all 26 project files to YAML frontmatter
  10. Rewrote parser with python-frontmatter and Pydantic models
  11. Build the portfolio frontend that consumes devlog export JSON
  12. DecidedUse git-backed markdown as storage
  13. ShippedPhase 1 features shipped: goal lifecycle, decisions log, typed journey
  14. DoneBuild the portfolio frontend that consumes devlog export JSON
  15. GoalImplement Phase 2: standup command + enrich AGENTS.md with decisions section
  16. Fixedtest blocker
  17. ShippedRenamed commands for semantic clarity: hurdle→block, get→show, clear→reset, Hurdles→Blockers across all 24 project files
  18. ShippedPhase 2 shipped: standup command aggregates goal, handoff, recent activity, decisions, and active blockers; AGENTS.md refresh now includes decisions and recent logs
  19. DoneImplement Phase 2: standup command + enrich AGENTS.md with decisions section