Skip to content

CLAUDE.md

Latest commit

 

History

History
260 lines (203 loc) · 7.22 KB

CLAUDE.md

File metadata and controls

260 lines (203 loc) · 7.22 KB

Claude Instructions

Project Overview

This is the Project Status Tracker - a comprehensive system for tracking project stages, progress, and metadata using loglog format. The system provides templates, automation scripts, bash aliases, and git hooks for seamless project status management.

Project Stage Definitions

1. Initial Setup

  • Repository created, basic structure in place
  • Template files copied and configured
  • Ready to start development

2. Proof of Concept (POC)

  • Validating core concept/technology
  • Experimenting with approaches
  • Not production-ready
  • Goal: Answer "Can this work?"

3. Minimum Viable Product (MVP)

  • First usable version with core features
  • May have bugs blocking demo/production
  • Focus on core functionality only
  • Goal: Get something working end-to-end

4. Beta Release

  • Feature-complete for v1.0 scope
  • Functional but missing polish features
  • Known list of features X, Y, Z to add
  • May have active testers/users
  • Goal: Refinement and feature completion

5. Production Ready

  • Stable, tested, documented
  • All planned features implemented
  • Ready for real-world use
  • Active maintenance

6. Maintenance Mode

  • Core features complete and stable
  • Nice-to-have features queued (A, B, C)
  • Only accepting specific contributions
  • Minimal active development

Development Commands

This project is primarily documentation and shell scripts. No build process required.

Testing Scripts

# Test the aggregation script
./update_project_status.sh

# Source aliases and test functions
source ./project_aliases.sh
list-projects
ps-help

Making Changes

  • Update scripts: Direct editing
  • Test locally before committing
  • Update STATUS.log when making changes
  • Keep README.md in sync with features

Git Workflow

  • Update STATUS.log "Last Updated" field when making changes
  • Run ./update_project_status.sh after STATUS.log updates
  • Use descriptive commit messages
  • Follow semantic versioning for releases

Implementation Rules

No creative liberties - Only implement what is explicitly discussed and decided

  • Never invent features without user approval
  • Always ask before adding new scripts or commands
  • Keep it simple - prefer plain bash over complex solutions

Documentation-first approach

  • Update README.md when adding features
  • Document new aliases in project_aliases.sh
  • Add examples for new functionality
  • Keep STATUS.log current

Decision-first workflow

  1. Discuss what to add/change
  2. Update documentation
  3. Implement the change
  4. Test thoroughly
  5. Update STATUS.log

Documentation Format

Use loglog format for all status tracking

  • STATUS.log files use loglog syntax
  • Convert to markdown when needed: loglog file.log > file.md
  • Follow loglog syntax from https://github.com/k1monfared/loglog
  • Installation: pip install loglog or cargo install loglog

Code Conventions

Shell Scripts

  • Use bash shebang: #!/bin/bash
  • Include descriptive comments
  • Quote variables properly
  • Use set -e for critical scripts
  • Provide usage examples in comments

File Naming

  • Scripts: lowercase with underscores (update_project_status.sh)
  • Config: lowercase (hooks.json, settings.json)
  • Documentation: uppercase or mixed case (README.md, CLAUDE.md, STATUS.log)

Templates

  • Keep templates generic and well-commented
  • Use placeholder text like YYYY-MM-DD
  • Provide examples in comments
  • Make it obvious what needs to be replaced

Testing Instructions

Manual Testing

  1. Create a test project folder
  2. Copy template files
  3. Fill in STATUS.log
  4. Run update_project_status.sh
  5. Verify master file is correctly generated
  6. Test all bash aliases

Integration Testing

  • Test with multiple projects
  • Test with missing STATUS.log files
  • Test with various stage types
  • Verify emoji indicators work correctly

Architecture Notes

Key Files

Core Scripts:

  • update_project_status.sh - Aggregates STATUS.log files into master
  • project_aliases.sh - Provides bash command shortcuts

Templates:

  • templates/claude_code_project_template/ - Full project template
    • STATUS.log - Status tracking template
    • CLAUDE.md - Claude instructions template
    • README.md - README template with status badge
    • .claude/hooks.json - Git hooks for auto-update

Documentation:

  • README.md - User-facing documentation
  • STATUS.log - This project's status
  • CLAUDE.md - This file (development guidelines)

Design Patterns

Template-based: All projects use same STATUS.log structure Aggregation: Master file generated from individual statuses Automation: Git hooks and scripts handle updates Visual: Emoji indicators for quick scanning Portable: Plain text, works everywhere

Environment Setup

Requirements

  • Bash shell (most Linux/macOS systems)
  • loglog (optional, for markdown conversion)
  • Git (optional, for version control)

Installation

# 1. Copy scripts to desired location
# 2. Make scripts executable
chmod +x update_project_status.sh project_aliases.sh

# 3. Add aliases to .bashrc
echo 'source /path/to/project_aliases.sh' >> ~/.bashrc
source ~/.bashrc

Configuration

Edit paths in scripts if not using default locations:

  • update_project_status.sh: MASTER_FILE, PUBLIC_DIR
  • project_aliases.sh: All alias paths

Project Status Tracking

This Project's STATUS.log

  • Maintain STATUS.log in this project
  • Update "Last Updated" date when making changes
  • Track new features in appropriate stage section
  • Document blockers and active tasks

Status Badges

README.md includes status badge: Status: 🟢 Production Ready | Mode: 🤖 Claude Code | Updated: 2026-01-13

Converting to Markdown

loglog STATUS.log > STATUS.md
loglog README.md > README_from_log.md

Contributing Guidelines

When contributing to this project:

  1. Test thoroughly: Verify scripts work in various scenarios
  2. Update docs: Keep README.md current with changes
  3. Follow format: Use existing patterns for consistency
  4. Keep simple: Prefer simple solutions over clever ones
  5. Plain text: No external dependencies if possible
  6. Cross-platform: Bash scripts should work on Linux/macOS/WSL

Common Tasks

Adding a New Alias

  1. Edit project_aliases.sh
  2. Add function or alias
  3. Document in ps-help function
  4. Update README.md with new command
  5. Test by sourcing the file

Modifying Aggregation Logic

  1. Edit update_project_status.sh
  2. Test with multiple projects
  3. Verify emoji indicators still work
  4. Check output format
  5. Update documentation if behavior changes

Adding Template Files

  1. Add file to templates/claude_code_project_template/
  2. Document in README.md
  3. Ensure it has placeholder values
  4. Test by copying to a new project

Creating Examples

  1. Create example project folder
  2. Fill in realistic data
  3. Include comments explaining choices
  4. Add to documentation

Maintenance Notes

  • This project is production-ready as of 2026-01-13
  • Future enhancements tracked in STATUS.log
  • Keep dependencies minimal
  • Preserve backward compatibility
  • Version major releases
  • Gather community feedback

Support

For issues or questions:

  • Check README.md first
  • Review STATUS.log for known issues
  • Open GitHub issue with details
  • Include bash version and OS info