up-cli 0.2.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

up/templates/docs/__init__.py

@@ -0,0 +1,341 @@
+"""Docs system templates."""
+
+from pathlib import Path
+
+def create_docs_system(target_dir: Path, force: bool = False) -> None:
+    """Create the documentation system structure."""
+    docs = target_dir / "docs"
+
+    # Create directory structure
+    dirs = [
+        "roadmap/vision",
+        "roadmap/phases",
+        "roadmap/sales",
+        "roadmap/implementation",
+        "changelog",
+        "architecture",
+        "features",
+        "guides",
+        "operations",
+        "development",
+        "research",
+        "todo",
+        # New SDLC folders
+        "decisions",
+        "handoff",
+        "learnings",
+        "tests",
+        "reviews",
+        "releases",
+    ]
+    for d in dirs:
+        (docs / d).mkdir(parents=True, exist_ok=True)
+
+    # Create template files
+    _create_main_readme(docs, force)
+    _create_context_file(docs, force)
+    _create_index_file(docs, force)
+    _create_roadmap_readme(docs, force)
+    _create_vision_template(docs, force)
+    _create_phase_templates(docs, force)
+    _create_changelog_readme(docs, force)
+    _create_folder_readmes(docs, force)
+    _create_sdlc_readmes(docs, force)
+
+
+def _create_main_readme(docs: Path, force: bool) -> None:
+    """Create main docs README."""
+    from datetime import date
+    content = f"""# Documentation
+
+**Updated**: {date.today().isoformat()}
+
+## Structure
+
+| Folder | Purpose |
+|--------|---------|
+| roadmap/ | Strategic planning |
+| architecture/ | System design |
+| features/ | Feature specs |
+| changelog/ | Progress tracking |
+| guides/ | User how-to |
+| todo/ | Future work |
+| decisions/ | ADRs |
+| handoff/ | Session continuity |
+| learnings/ | Patterns discovered |
+| tests/ | Test documentation |
+| reviews/ | Code reviews |
+| releases/ | Release notes |
+
+## Key Files
+
+- `CONTEXT.md` - AI reads first (current state)
+- `INDEX.md` - Quick reference to find docs
+- `handoff/LATEST.md` - Most recent session handoff
+"""
+    _write_file(docs / "README.md", content, force)
+
+
+def _write_file(path: Path, content: str, force: bool) -> None:
+    """Write file if it doesn't exist or force is True."""
+    if path.exists() and not force:
+        return
+    path.write_text(content)
+
+
+def _create_roadmap_readme(docs: Path, force: bool) -> None:
+    """Create roadmap README."""
+    content = """# Project Roadmap
+
+**Created**: {date}
+**Status**: 🔄 Active
+
+---
+
+## Overview
+
+This roadmap defines the evolution of the project.
+
+## Current Status
+
+| Phase | Status | Progress |
+|-------|--------|----------|
+| Phase 1: Foundation | 📋 Planned | 0% |
+| Phase 2: Intelligence | 📋 Planned | 0% |
+| Phase 3: Scale | 📋 Planned | 0% |
+
+## Folder Structure
+
+```
+docs/roadmap/
+├── README.md              (this file)
+├── vision/                (Product Vision)
+├── phases/                (Phase Roadmaps)
+├── sales/                 (Sales Materials)
+└── implementation/        (Implementation Plans)
+```
+
+## Quick Links
+
+- [Product Vision](./vision/PRODUCT_VISION.md)
+- [Phase 1](./phases/PHASE_1_FOUNDATION.md)
+- [Implementation Status](./implementation/STATUS.md)
+"""
+    from datetime import date
+    content = content.replace("{date}", date.today().isoformat())
+    _write_file(docs / "roadmap/README.md", content, force)
+
+
+def _create_vision_template(docs: Path, force: bool) -> None:
+    """Create product vision template."""
+    content = """# Product Vision
+
+**Created**: {date}
+**Status**: 📋 Draft
+
+---
+
+## The Vision
+
+> **One-line vision statement here**
+
+## Problem Statement
+
+| Pain Point | Impact |
+|------------|--------|
+| Problem 1 | Description |
+| Problem 2 | Description |
+
+## Solution
+
+Brief description of the solution.
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Metric 1 | Value |
+| Metric 2 | Value |
+"""
+    from datetime import date
+    content = content.replace("{date}", date.today().isoformat())
+    _write_file(docs / "roadmap/vision/PRODUCT_VISION.md", content, force)
+
+
+def _create_phase_templates(docs: Path, force: bool) -> None:
+    """Create phase template files."""
+    from datetime import date
+    today = date.today().isoformat()
+
+    phase1 = f"""# Phase 1: Foundation
+
+**Timeline**: Q1
+**Status**: 📋 Planned
+
+---
+
+## Objectives
+
+1. Objective 1
+2. Objective 2
+
+## Deliverables
+
+| Task | Priority | Status |
+|------|----------|--------|
+| Task 1 | 🔴 Critical | 📋 Planned |
+| Task 2 | 🟠 High | 📋 Planned |
+
+## Success Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+"""
+    _write_file(docs / "roadmap/phases/PHASE_1_FOUNDATION.md", phase1, force)
+
+
+def _create_changelog_readme(docs: Path, force: bool) -> None:
+    """Create changelog README."""
+    content = """# Changelog
+
+**Purpose**: Track progress and changes.
+
+## Format
+
+Each entry: `YYYY-MM-DD-topic.md`
+
+## Template
+
+```markdown
+# Change Title
+
+**Date**: YYYY-MM-DD
+**Status**: ✅ Completed
+
+## Summary
+Brief overview
+
+## Changes
+- Change 1
+- Change 2
+```
+"""
+    _write_file(docs / "changelog/README.md", content, force)
+
+
+def _create_folder_readmes(docs: Path, force: bool) -> None:
+    """Create README for each folder."""
+    folders = {
+        "architecture": "System design docs",
+        "features": "Feature specifications",
+        "operations": "Deployment guides",
+        "development": "Developer guides",
+        "guides": "User how-to guides",
+        "research": "Research notes",
+        "todo": "Future work tracking",
+    }
+    for folder, purpose in folders.items():
+        content = f"# {folder.title()}\n\n**Purpose**: {purpose}\n"
+        _write_file(docs / folder / "README.md", content, force)
+
+
+def _create_context_file(docs: Path, force: bool) -> None:
+    """Create CONTEXT.md - AI reads this first."""
+    from datetime import date
+    content = f"""# Project Context
+
+**Updated**: {date.today().isoformat()}
+**Status**: 🔄 Active
+
+---
+
+## Current State
+
+| Aspect | Status |
+|--------|--------|
+| Phase | Planning |
+| Focus | Initial setup |
+| Blockers | None |
+
+## Recent Changes
+
+- Project initialized
+
+## Next Steps
+
+1. Define project vision
+2. Set up development environment
+3. Begin implementation
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| CLAUDE.md | AI instructions |
+| docs/handoff/LATEST.md | Session continuity |
+"""
+    _write_file(docs / "CONTEXT.md", content, force)
+
+
+def _create_sdlc_readmes(docs: Path, force: bool) -> None:
+    """Create README files for SDLC folders."""
+    sdlc_folders = {
+        "decisions": ("Architecture Decision Records", "ADR-NNN-title.md"),
+        "handoff": ("Session continuity for AI agents", "LATEST.md"),
+        "learnings": ("Patterns and anti-patterns discovered", "YYYY-MM-DD-topic.md"),
+        "tests": ("Test documentation and coverage", "component-tests.md"),
+        "reviews": ("Code and design reviews", "YYYY-MM-DD-review.md"),
+        "releases": ("Release notes and versioning", "vX.Y.Z-YYYY-MM-DD.md"),
+    }
+    for folder, (purpose, fmt) in sdlc_folders.items():
+        content = f"# {folder.title()}\n\n**Purpose**: {purpose}\n\n**Format**: `{fmt}`\n"
+        _write_file(docs / folder / "README.md", content, force)
+
+
+def _create_index_file(docs: Path, force: bool) -> None:
+    """Create INDEX.md - Quick reference for AI to find docs."""
+    from datetime import date
+    content = f"""# Documentation Index
+
+**Updated**: {date.today().isoformat()}
+
+> AI: Use this index to quickly find relevant documentation.
+
+---
+
+## Quick Reference
+
+| Topic | File | Description |
+|-------|------|-------------|
+| Project State | CONTEXT.md | Current status, blockers, next steps |
+| Recent Work | handoff/LATEST.md | Last session summary |
+| Vision | roadmap/vision/PRODUCT_VISION.md | Product goals |
+| Phase 1 | roadmap/phases/PHASE_1_FOUNDATION.md | Current phase |
+
+## By Category
+
+### Architecture
+| Topic | File |
+|-------|------|
+| *Add architecture docs here* | architecture/*.md |
+
+### Features
+| Topic | File |
+|-------|------|
+| *Add feature specs here* | features/*.md |
+
+### Decisions
+| Topic | File |
+|-------|------|
+| *Add ADRs here* | decisions/ADR-*.md |
+
+---
+
+## How to Update
+
+When adding new docs, update this index:
+1. Add entry to relevant category table
+2. Keep descriptions brief (5-10 words)
+3. Use relative paths
+"""
+    _write_file(docs / "INDEX.md", content, force)

up/templates/docs/standards/HEADERS.md

@@ -0,0 +1,24 @@
+# Header Standards
+
+## Required Header
+
+```markdown
+# Document Title
+
+**Created**: YYYY-MM-DD
+**Updated**: YYYY-MM-DD
+**Status**: [emoji] [description]
+**Priority**: High/Medium/Low
+
+---
+```
+
+## Status Values
+
+| Status | Emoji | Use When |
+|--------|-------|----------|
+| Complete | ✅ | 100% done |
+| In Progress | 🚧 | Active work |
+| Planned | 📋 | Future work |
+| Draft | 📝 | Early stage |
+| Blocked | 🔴 | Blocked |

up/templates/docs/standards/STRUCTURE.md

@@ -0,0 +1,18 @@
+# Folder Structure
+
+```
+docs/
+├── README.md
+├── roadmap/
+│   ├── vision/
+│   ├── phases/
+│   └── sales/
+├── architecture/
+├── features/
+├── changelog/
+├── guides/
+├── operations/
+├── development/
+├── research/
+└── todo/
+```

up/templates/docs/standards/TEMPLATES.md

@@ -0,0 +1,19 @@
+# Document Templates
+
+## Feature Template
+
+```markdown
+# Feature: [Name]
+
+**Created**: YYYY-MM-DD
+**Status**: 📋 Planned
+
+---
+
+## Overview
+Brief description.
+
+## Requirements
+- Requirement 1
+- Requirement 2
+```

up/templates/loop/__init__.py

@@ -62,12 +62,22 @@ OBSERVE → CHECKPOINT → EXECUTE → VERIFY → COMMIT
 
 ## Commands
 
+### Skill Commands (for AI)
 | Command | Description |
 |---------|-------------|
 | `/product-loop` | Start the development loop |
 | `/product-loop resume` | Resume from last checkpoint |
 | `/product-loop status` | Show current state |
-| `/product-loop rollback` | Rollback last change |
+
+### CLI Commands (for users)
+| Command | Description |
+|---------|-------------|
+| `up start` | Start the product loop |
+| `up start --resume` | Resume from checkpoint |
+| `up start --parallel` | Run tasks in parallel |
+| `up save` | Create checkpoint |
+| `up reset` | Rollback to checkpoint |
+| `up status` | Show current state |
 
 ---
 
@@ -93,16 +103,16 @@ Prevents infinite loops on persistent failures.
 ### Phase 1: OBSERVE
 
 Read task sources in priority order:
-1. `.loop_state.json` - Resume interrupted task
+1. `.up/state.json` - Resume interrupted task (unified state)
 2. `prd.json` - Structured user stories
 3. `TODO.md` - Feature backlog
 
 ### Phase 2: CHECKPOINT
 
 Before risky operations:
-- Create git stash checkpoint
+- Create git checkpoint via `up save`
 - Record modified files
-- Save state to `.loop_state.json`
+- Save state to `.up/state.json`
 
 ### Phase 3: EXECUTE
 
@@ -129,22 +139,26 @@ On success:
 
 ---
 
-## State File: `.loop_state.json`
+## State File: `.up/state.json`
+
+The unified state file stores loop state, context budget, agent state, and metrics:
 
 ```json
 {
-  "version": "1.0",
-  "iteration": 5,
-  "phase": "VERIFY",
-  "current_task": "US-003",
-  "tasks_completed": ["US-001", "US-002"],
-  "circuit_breaker": {
-    "test": {"failures": 0, "state": "CLOSED"},
-    "build": {"failures": 0, "state": "CLOSED"}
+  "version": "2.0",
+  "loop": {
+    "iteration": 5,
+    "phase": "VERIFY",
+    "current_task": "US-003",
+    "tasks_completed": ["US-001", "US-002"],
+    "tasks_failed": [],
+    "last_checkpoint": "cp-20260204-123456"
+  },
+  "circuit_breakers": {
+    "task": {"failures": 0, "state": "CLOSED"}
   },
-  "checkpoints": [],
   "metrics": {
-    "total_edits": 15,
+    "total_tasks": 15,
     "total_rollbacks": 1,
     "success_rate": 0.93
   }
@@ -178,7 +192,7 @@ timeout_per_operation: 120s
 ## Quick Start
 
 1. Ensure `prd.json` or `TODO.md` exists with tasks
-2. Run `/product-loop`
+2. Run `/product-loop` or `up start`
 3. Loop will:
    - Pick highest priority task
    - Create checkpoint
@@ -197,6 +211,17 @@ This skill respects context budget:
 
 ---
 
+## Implementation Note
+
+The actual implementation is in `src/up/core/`:
+- `state.py` - Unified state management with circuit breaker
+- `checkpoint.py` - Git checkpoint operations
+- `provenance.py` - AI operation tracking
+
+The Python files in this skill folder (`circuit_breaker.py`, `state_manager.py`) are **reference implementations** for understanding the patterns. The CLI uses the implementations in `src/up/core/`.
+
+---
+
 ## Status Output Format
 
 ```
@@ -204,7 +229,7 @@ This skill respects context budget:
  PRODUCT LOOP - Iteration #5
 ═══════════════════════════════════════════
  Health:     ✅ HEALTHY
- Circuit:    test=CLOSED build=CLOSED
+ Circuit:    task=CLOSED
  Task:       US-003 Add authentication
  Status:     ✅ COMPLETE
 ───────────────────────────────────────────
@@ -523,28 +548,63 @@ if __name__ == "__main__":
 
 
 def _create_loop_state(target_dir: Path, force: bool) -> None:
-    """Create initial loop state file."""
+    """Create initial unified state file in .up/ directory."""
     today = date.today().isoformat()
+    
+    # Create .up directory
+    up_dir = target_dir / ".up"
+    up_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Unified state file
     content = f"""{{
-  "version": "1.0",
-  "iteration": 0,
-  "phase": "INIT",
-  "current_task": null,
-  "tasks_completed": [],
-  "tasks_remaining": [],
-  "circuit_breaker": {{
-    "test": {{"failures": 0, "state": "CLOSED"}},
-    "build": {{"failures": 0, "state": "CLOSED"}},
-    "lint": {{"failures": 0, "state": "CLOSED"}}
+  "version": "2.0",
+  "loop": {{
+    "iteration": 0,
+    "phase": "INIT",
+    "current_task": null,
+    "tasks_completed": [],
+    "tasks_failed": [],
+    "last_checkpoint": null,
+    "doom_loop_threshold": 3
+  }},
+  "context": {{
+    "budget": 100000,
+    "used": 0,
+    "warning_threshold": 0.8,
+    "critical_threshold": 0.9
+  }},
+  "parallel": {{
+    "active": false,
+    "max_workers": 3,
+    "active_worktrees": []
   }},
   "checkpoints": [],
+  "circuit_breakers": {{
+    "task": {{"failures": 0, "state": "CLOSED", "last_failure": null}}
+  }},
   "metrics": {{
-    "total_edits": 0,
+    "total_tasks": 0,
     "total_rollbacks": 0,
-    "success_rate": 1.0
+    "success_rate": 1.0,
+    "session_start": "{today}"
   }},
   "created_at": "{today}",
-  "last_updated": "{today}"
+  "updated_at": "{today}"
 }}
 """
-    _write_file(target_dir / ".loop_state.json", content, force)
+    _write_file(up_dir / "state.json", content, force)
+    
+    # Also create config.json with defaults
+    config_content = """{
+  "doom_loop_threshold": 3,
+  "circuit_breaker_cooldown_minutes": 5,
+  "circuit_breaker_failure_threshold": 3,
+  "checkpoint_retention_count": 50,
+  "context_budget": 100000,
+  "context_warning_threshold": 0.8,
+  "context_critical_threshold": 0.9,
+  "ai_timeout_seconds": 600,
+  "parallel_max_workers": 3
+}
+"""
+    _write_file(up_dir / "config.json", config_content, force)

up/ui/__init__.py

@@ -0,0 +1,14 @@
+"""UP-CLI UI Components.
+
+Cybersecurity/AI themed terminal UI for the product loop.
+"""
+
+from up.ui.theme import CyberTheme, THEME
+from up.ui.loop_display import ProductLoopDisplay, TaskStatus
+
+__all__ = [
+    "CyberTheme",
+    "THEME", 
+    "ProductLoopDisplay",
+    "TaskStatus",
+]