├── .claude └── commands │ └── simone │ ├── code_review.md │ ├── commit.md │ ├── create_general_task.md │ ├── create_sprint_tasks.md │ ├── create_sprints_from_milestone.md │ ├── discuss_review.md │ ├── do_task.md │ ├── initialize.md │ ├── prime.md │ ├── project_review.md │ ├── test.md │ ├── testing_review.md │ └── yolo.md ├── .gitignore ├── .simone ├── 00_PROJECT_MANIFEST.md ├── 01_PROJECT_DOCS │ └── ARCHITECTURE.md ├── 02_REQUIREMENTS │ ├── CLAUDE.md │ └── M01_Backend_Setup │ │ ├── M01_milestone_meta.md │ │ ├── PRD_AMEND_01_Auth_Flow_Update.md │ │ ├── PRD_Backend_Setup.md │ │ └── SPECS_API_V1.md ├── 03_SPRINTS │ ├── CLAUDE.MD │ └── S01_M01_Initial_API │ │ ├── S01_sprint_meta.md │ │ └── T01_S01_Setup_Project_Structure.md ├── 04_GENERAL_TASKS │ ├── CLAUDE.MD │ ├── T002_API_Rate_Limiting.md │ └── TX001_Refactor_Logging_Module.md ├── 05_ARCHITECTURAL_DECISIONS │ ├── ADR001_Chosen_Database_System.md │ └── ADR002_API_Authentication_Method.md ├── 99_TEMPLATES │ ├── adr_template.md │ ├── milestone_meta_template.md │ ├── project_manifest_template.md │ ├── sprint_meta_template.md │ └── task_template.md ├── CLAUDE.MD └── README.md ├── CHANGELOG.md ├── LICENSE ├── README.md ├── SYNC_GUIDE.md └── sync-simone.sh /.claude/commands/simone/code_review.md: -------------------------------------------------------------------------------- 1 | # Code Review - Execute top to bottom 2 | 3 | Use the following instructions from top to bottom to execute a Code Review. 4 | 5 | ## Create a TODO with EXACTLY these 6 Items 6 | 7 | 1. Analyze the Scope given 8 | 2. Find code changes within Scope 9 | 3. Find relevant Specification and Documentation 10 | 4. Compare code changes against Documentation and Requirements 11 | 5. Analyze possible differences 12 | 6. Provide PASS/FAIL verdict with details 13 | 14 | Follow step by step and adhere closely to the following instructions for each step. 15 | 16 | ## DETAILS on every TODO item 17 | 18 | ### 1. Analyze the Scope given 19 | 20 | check: <$ARGUMENTS> 21 | 22 | If empty, use default, otherwise interpret <$ARGUMENTS> to identify the scope of the Review. Only continue if you can find meaningful changes to review. 23 | 24 | **CONTEXT:** Before reviewing code changes: 25 | 26 | - Read `.simone/00_PROJECT_MANIFEST.md` to understand current sprint and milestone context 27 | - Use the manifest to identify which sprint is active and what work is in scope 28 | - Only evaluate against requirements appropriate for the current sprint's deliverables 29 | 30 | ### 2. Find code changes within Scope 31 | 32 | With the identified Scope use `git diff` (on default: `git diff HEAD~1`) to find code changes. 33 | 34 | ### 3. Find relevant Specifications and Documentation 35 | 36 | - FIND the Task, Sprint and Milestone involved in the work that was done and output your findings 37 | - Navigate to `.simone/03_SPRINTS/` to find the current sprint directory 38 | - READ the sprint meta file to understand sprint objectives and deliverables 39 | - If a specific task is in scope, find and READ the task file in the sprint directory 40 | - IDENTIFY related requirements in `.simone/02_REQUIREMENTS/` for the current milestone 41 | - READ involved Documents especially in `.simone/01_PROJECT_DOCS/` and `.simone/02_REQUIREMENTS/` 42 | - **IMPORTANT:** Focus on current sprint deliverables, not future milestone features 43 | 44 | ### 4. Compare code changes against Documentation and Requirements 45 | 46 | - Use DEEP THINKING to compare changes against found Requirements and Specs. 47 | - Compare especially these things: 48 | - **Data models / schemas** — fields, types, constraints, relationships. 49 | - **APIs / interfaces** — endpoints, params, return shapes, status codes, errors. 50 | - **Config / environment** — keys, defaults, required/optional. 51 | - **Behaviour** — business rules, side-effects, error handling. 52 | - **Quality** — naming, formatting, tests, linter status. 53 | 54 | **IMPORTANT**: 55 | 56 | - Deviations from the Specs is not allowed. Not even small ones. Be very picky here! 57 | - If in doubt call a **FAIL** and ask the User. 58 | - Zero tolerance on not following the Specs and Documentation. 59 | 60 | ### 5. Analyze the differences 61 | 62 | - Analyze any difference found 63 | - Give every issue a Severity Score 64 | - Severity ranges from 1 (low) to 10 (high) 65 | - Remember List of issues and Scores for output 66 | 67 | ### 6. Provide PASS/FAIL verdict with details 68 | 69 | - Call a **FAIL** on any differences found. 70 | - Zero Tolerance - even on well meant additions. 71 | - Leave it on the user to decide if small changes are allowed. 72 | - Only **PASS** if no discrepancy appeared. 73 | 74 | #### IMPORTANT: Output Format 75 | 76 | - Output the results of your review to the task's **## Output Log** section in the task file 77 | - Find the task file in `.simone/03_SPRINTS/` or `.simone/04_GENERAL_TASKS/` based on the scope 78 | - Append the review results to the existing Output Log with timestamp 79 | - Output Format: 80 | ``` 81 | [YYYY-MM-DD HH:MM]: Code Review - PASS/FAIL 82 | Result: **FAIL/PASS** Your final decision on if it's a PASS or a FAIL. 83 | **Scope:** Inform the user about the review scope. 84 | **Findings:** Detailed list with all Issues found and Severity Score. 85 | **Summary:** Short summary on what is wrong or not. 86 | **Recommendation:** Your personal recommendation on further steps. 87 | ``` 88 | - Also output a brief result summary to the console for immediate feedback 89 | -------------------------------------------------------------------------------- /.claude/commands/simone/commit.md: -------------------------------------------------------------------------------- 1 | # Analyze changes and create logical git commits with user confirmation 2 | 3 | Follow these instructions from top to bottom. 4 | 5 | ## Create a TODO with EXACTLY these 6 items 6 | 7 | 1. Parse arguments and analyze git status 8 | 2. Review changes and group by logical commits 9 | 3. Propose commit structure and messages 10 | 4. Check if user approval is necessary 11 | 5. Execute approved commits 12 | 6. Report commit results 13 | 14 | --- 15 | 16 | ## 1 · Analyze git status and parse arguments 17 | 18 | - Run these commands in parallel for maximum efficiency: `git status`, `git diff --staged`, `git diff` 19 | - List all changed files with their folder structure to understand the scope 20 | 21 | ### CRITICAL: Argument Interpretation Rules 22 | 23 | **Context Provided** (when <$ARGUMENTS> contains text): 24 | 25 | - If YOLO is part of the <$ARGUMENTS> it is meant to skip user Approval (see Step 4 on your Todo) 26 | - The other text in <$ARGUMENTS> represents a **task ID**, **sprint ID**, or other **contextual identifier** provided by the user 27 | - This is NOT a file path - it's a semantic context for filtering changes 28 | - **PRIMARY FOCUS**: Only commit files directly related to this context 29 | - **SECONDARY CONSIDERATION**: After handling the primary context, ask if user wants to commit other unrelated changes 30 | 31 | **Task ID Pattern** (e.g., T01_S02, TX03_S01, T003): 32 | 33 | - Sprint Tasks: `T_S` format (e.g., T01_S02, T03_S02) 34 | - Completed Sprint Tasks: `TX_S` format (e.g., TX01_S02, TX03_S01) 35 | - General Tasks: `T` format (e.g., T001, T002) 36 | - Completed General Tasks: `TX` format (e.g., TX001, TX002) 37 | - Search for this task ID in: 38 | - `.simone/03_SPRINTS/` directory (for sprint tasks) 39 | - `.simone/04_GENERAL_TASKS/` directory (for general tasks) 40 | - Task metadata in files (look for `task_id: T01_S02` in frontmatter) 41 | - Git diff content (to see if code comments or commits reference the task) 42 | - Identify ALL files that were modified as part of this task's implementation 43 | - This includes: source code, tests, configuration, and the task documentation file itself 44 | 45 | **Sprint ID Pattern** (e.g., S01, S02): 46 | 47 | - When only sprint ID is provided, commit all changes related to ANY task within that sprint 48 | - Search pattern: `T*_S` in the sprint directory 49 | - Example: "S02" would include changes for T01_S02, T02_S02, T03_S02, etc. 50 | 51 | **No Context Provided** (when <$ARGUMENTS> is empty): 52 | 53 | - Analyze all changes and group them logically 54 | - Propose separate commits for different logical units of work 55 | 56 | ### Implementation Steps 57 | 58 | 1. First, determine if <$ARGUMENTS> contains any text 59 | 2. If yes, explicitly state: "Context provided: '$ARGUMENTS' - I will focus on changes related to this context" 60 | 3. If it's a task ID pattern, find the task file and understand what was implemented 61 | 4. Filter the changed files to only those related to the identified context 62 | 5. If no files match the context, inform the user: "No changes found related to '$ARGUMENTS'" 63 | 6. If unrelated changes exist, mention them but DO NOT include in initial commit proposal 64 | 65 | ## 2 · Review changes and group by logical commits 66 | 67 | ### PRIORITY: Context Filtering 68 | 69 | **If context provided in arguments**: 70 | 71 | 1. **FILTER FIRST**: Separate changes into two groups: 72 | - **Related to context**: Files that are part of the task/context implementation 73 | - **Unrelated to context**: Everything else 74 | 2. **FOCUS**: Only analyze the "related to context" group for the first commit 75 | 3. **DEFER**: Keep the "unrelated" group for potential later commits (only if user requests) 76 | 77 | **Standard grouping logic** (for no-context or within-context grouping): 78 | 79 | - **Think about** which changes belong together logically: 80 | - Task completion (group by task ID when applicable) 81 | - Feature additions (group by feature scope) 82 | - Configuration updates (group separately) 83 | - Documentation updates (group by documentation type) 84 | - Bug fixes (group by related functionality) 85 | - **Think carefully** to ensure each commit represents one logical change that can be understood and potentially reverted independently 86 | - Avoid mixing unrelated changes in the same commit 87 | - Consider dependencies between changes when ordering commits 88 | 89 | ## 3 · Propose commit 90 | 91 | ### Context-Aware Commit Proposal 92 | 93 | **When context was provided** (e.g., task ID): 94 | 95 | - **FIRST COMMIT**: Must contain ONLY files related to the provided context 96 | - State clearly: "This commit includes changes for $ARGUMENTS" 97 | - After this commit is done, then ask: "There are also unrelated changes in [list files]. Would you like me to create additional commits for these?" 98 | 99 | **When no context provided**: 100 | 101 | - Propose commits based on logical grouping of all changes 102 | 103 | For the next commit to create: 104 | 105 | - **Context**: If applicable, which task/context this commit addresses 106 | - **Files**: List the specific files to be included 107 | - **Commit message**: Use conventional commit format, be clear and concise 108 | - **CRITICAL:** Must not contain any attribution to Claude, Anthropic, or AI assistance 109 | - If task-related, include task ID in message (e.g., "feat(agents): implement T01_S02 coordinator agent" or "fix(api): resolve T003 authentication issue") 110 | - **Reasoning**: Brief explanation of why these changes belong together 111 | 112 | ## 4 · Check if user approval is necessary 113 | 114 | If YOLO **IS** part of the <$ARGUMENTS> skip this and jump to next step. 115 | 116 | Otherwise ask the User for approval. 117 | 118 | - Show the complete commit plan including files and message 119 | - Wait for explicit user confirmation before proceeding 120 | - If user says no, ask what should be changed 121 | - If user wants to modify the commit message or scope, make adjustments 122 | 123 | ## 5 · Execute approved commit and continue 124 | 125 | For the approved commit: 126 | 127 | - Stage the specified files with `git add` 128 | - **IMPORTANT:** We are using pre-commit hooks that will likely report shortcomings. You need to fix them. Don't skip validation unless there are open tasks adressing especially these problems. 129 | - **Create the commit** with the approved message 130 | - Verify commit was created successfully 131 | - **IMPORTANT:** If there are more commits remaining, return to step 3 for the next commit 132 | - Only proceed to step 6 when all commits are completed 133 | 134 | ## 6 · Report commit results 135 | 136 | Provide summary: 137 | 138 | - **Commits Created**: List each commit with SHA and message 139 | - **Files Committed**: Total count of files committed 140 | - **Remaining Changes**: Any uncommitted changes still pending 141 | - **Repository Status**: Current git status after commits 142 | -------------------------------------------------------------------------------- /.claude/commands/simone/create_general_task.md: -------------------------------------------------------------------------------- 1 | # Create General Task - Execute top to bottom 2 | 3 | Creates a new general task in `.simone/04_GENERAL_TASKS/` following project documentation standards. 4 | 5 | ## Create a TODO with EXACTLY these 10 Items 6 | 7 | 1. Parse task arguments and determine task ID 8 | 2. Load project context and documentation requirements 9 | 3. Verify task doesn't duplicate existing work 10 | 4. Research codebase for implementation context 11 | 5. Create task file using standard template 12 | 6. Fill in task details with proper context 13 | 7. Add technical guidance and codebase references 14 | 8. Update project manifest with new task 15 | 9. Validate task alignment with architecture 16 | 10. Perform final quality check and report 17 | 18 | ## DETAILS on every TODO item 19 | 20 | ### 1. Parse task arguments and determine task ID 21 | 22 | The argument format is: `` 23 | 24 | - If arguments are empty, prompt user for task details 25 | - Generate sequential task ID by examining existing tasks in `.simone/04_GENERAL_TASKS/` 26 | - Find highest task number (T###) and increment by 1 27 | - Format: `T###_.md` 28 | - **IMPORTANT:** Task IDs must be sequential with no gaps 29 | 30 | ### 2. Load project context and documentation requirements 31 | 32 | Use PARALLEL SUBAGENTS to READ and UNDERSTAND the project's context: 33 | 34 | - READ `.simone/00_PROJECT_MANIFEST.md` - Get current project state 35 | - READ `.simone/01_PROJECT_DOCS/ARCHITECTURE.md` - Understand system constraints 36 | - READ `.simone/01_PROJECT_DOCS/LONG_TERM_VISION.md` - Understand future direction 37 | - READ latest files in `.simone/10_STATE_OF_PROJECT/` - Review current state 38 | - SCAN `.simone/05_ARCHITECTURE_DECISIONS/` for relevant ADRs 39 | - **IMPORTANT:** General tasks must align with documented architecture 40 | 41 | ### 3. Verify task doesn't duplicate existing work 42 | 43 | **SEARCH** comprehensively for potential duplicates: 44 | 45 | - Check all files in `.simone/04_GENERAL_TASKS/` 46 | - Search sprint tasks in `.simone/03_SPRINTS/*/T*.md` 47 | - Look for similar functionality in completed milestones 48 | - **CRITICAL:** If duplicate found, stop and report to user with file reference 49 | 50 | ### 4. Research codebase for implementation context 51 | 52 | Based on the task description, use PARALLEL SUBAGENTS to: 53 | 54 | - SEARCH for existing patterns similar to what the task requires 55 | - IDENTIFY key interfaces, classes, or modules that will be affected 56 | - FIND examples of similar implementations in the codebase 57 | - LOCATE relevant test patterns and existing test files 58 | - DISCOVER error handling and logging patterns used 59 | - MAP OUT integration points with existing code 60 | - **DOCUMENT** all findings for inclusion in task 61 | 62 | ### 5. Create task file using standard template 63 | 64 | **USE** the task template in `.simone/99_TEMPLATES/task_template.md` as base structure: 65 | 66 | - Copy template structure exactly 67 | - Place file in `.simone/04_GENERAL_TASKS/T###_.md` 68 | - Include timestamp: Execute `date '+%Y-%m-%d %H:%M:%S'` for creation time 69 | - **IMPORTANT:** Follow template structure precisely - no deviations 70 | 71 | ### 6. Fill in task details with proper context 72 | 73 | Populate the task file with: 74 | 75 | - **Title**: Clear, actionable task name 76 | - **Context**: Link to architecture docs and project state 77 | - **Requirements**: Specific, measurable outcomes 78 | - **Acceptance Criteria**: Clear definition of done 79 | - **Dependencies**: Reference relevant sprints/milestones 80 | - **Implementation Notes**: Technical approach aligned with architecture 81 | - **CRITICAL:** All content must reference existing documentation 82 | 83 | ### 7. Add technical guidance and codebase references 84 | 85 | **Technical Guidance section:** 86 | 87 | - Key interfaces and integration points discovered in step 4 88 | - Specific imports and module references from codebase 89 | - Existing patterns to follow (with file references) 90 | - Database models or API contracts to work with 91 | - Error handling approach used in similar code 92 | - Testing patterns found in the codebase 93 | 94 | **Implementation Notes section:** 95 | 96 | - Step-by-step implementation approach based on research 97 | - Key architectural decisions to respect (reference ADRs) 98 | - Specific files and functions to modify or extend 99 | - Testing approach based on existing test patterns 100 | - Performance considerations if relevant 101 | 102 | **IMPORTANT:** Do NOT include code examples. Provide structural guidance and file references only. 103 | 104 | ### 8. Update project manifest with new task 105 | 106 | **UPDATE** `.simone/00_PROJECT_MANIFEST.md`: 107 | 108 | - Add task to "## General Tasks" section 109 | - Format: `- [ ] T###: [Task Title] - Status: Not Started` 110 | - Maintain alphabetical/numerical ordering 111 | - Link to task file: `[T###](04_GENERAL_TASKS/T###_Title.md)` 112 | - **IMPORTANT:** Preserve all existing content 113 | 114 | ### 9. Validate task alignment with architecture 115 | 116 | **VERIFY** task compliance: 117 | 118 | - Check task doesn't contradict architecture principles 119 | - Ensure implementation approach uses established patterns 120 | - Validate dependencies exist and are correct 121 | - Confirm task scope is appropriate (not too broad/narrow) 122 | - Technical guidance aligns with existing codebase patterns 123 | - **CRITICAL:** Documentation is source of truth - any deviation needs justification 124 | 125 | ### 10. Perform final quality check and report 126 | 127 | **QUALITY CHECK**: 128 | 129 | - Task file follows template completely 130 | - All sections properly filled including new technical guidance 131 | - References to documentation and codebase are valid 132 | - Task ID is sequential and unique 133 | - Manifest updated correctly 134 | - Technical guidance references actual files and patterns 135 | - No scope creep or architecture violations 136 | 137 | **OUTPUT FORMAT**: 138 | 139 | ```markdown 140 | ✅ **Created**: T###_<Title>.md 141 | 📋 **Type**: General Task 142 | 🎯 **Purpose**: [One-line summary] 143 | 📚 **References**: [Key documentation links] 144 | 🔧 **Key Integration Points**: [Main files/modules to modify] 145 | 🧪 **Test Approach**: [Testing pattern to follow] 146 | ⏭️ **Next Step**: Review task details and run `/do_task T###` to begin 147 | ``` 148 | -------------------------------------------------------------------------------- /.claude/commands/simone/create_sprint_tasks.md: -------------------------------------------------------------------------------- 1 | # Create Tasks for Sprint - Execute top to bottom 2 | 3 | Create detailed tasks for an existing sprint with integrated implementation guidance. 4 | 5 | ## Create a TODO with EXACTLY these 8 Items 6 | 7 | 1. Identify target sprint and verify it exists 8 | 2. Load sprint context and related documentation 9 | 3. Check for existing ADRs and technical guidance 10 | 4. Analyze sprint deliverables for task breakdown 11 | 5. Create individual task files with implementation guidance 12 | 6. Link ADRs to relevant tasks 13 | 7. Update sprint meta with task references 14 | 8. Check quality of your work 15 | 16 | Follow step by step and adhere closely to the following instructions for each step. 17 | 18 | ## DETAILS on every TODO item 19 | 20 | ### 1. Identify target sprint and verify it exists 21 | 22 | Check: <$ARGUMENTS> 23 | 24 | **REQUIRED:** Sprint ID must be provided (e.g., S02). If empty, ask user to specify which sprint to detail. 25 | 26 | - VERIFY sprint directory exists in `.simone/03_SPRINTS/` 27 | - CHECK sprint meta file exists (e.g., `S02_sprint_meta.md`) 28 | - VERIFY sprint status is not already "completed" 29 | - If tasks already exist, ask user if they want to recreate them or any other guidance 30 | 31 | ### 2. Load sprint context and related documentation 32 | 33 | Use PARALLEL SUBAGENTS to READ and UNDERSTAND the project's context: 34 | 35 | - READ `.simone/00_PROJECT_MANIFEST.md` for project context 36 | - READ sprint meta file completely to understand goals and deliverables 37 | - READ parent milestone requirements from `.simone/02_REQUIREMENTS/` 38 | - READ `.simone/01_PROJECT_DOCS/ARCHITECTURE.md` for technical context 39 | - READ `.simone/01_PROJECT_DOCS/LONG_TERM_VISION.md` to understand architectural decisions 40 | 41 | **IMPORTANT:** Sprint tasks must align with documented sprint goals, not expand scope. 42 | 43 | ### 3. Check for existing ADRs and technical guidance 44 | 45 | **USE PARALLEL SUBAGENTS** to execute these commands: 46 | 47 | - SEARCH `.simone/05_ARCHITECTURE_DECISIONS/` for ADRs matching sprint ID (e.g., `ADR*_S02_*.md`) 48 | - READ all found ADRs to understand technical decisions 49 | - CHECK sprint meta for ADR references section 50 | - NOTE which technical decisions will affect task implementation 51 | - BUILD RELATIONSHIP in task and subtasks and make clear what to implement 52 | 53 | **If conflict in Scope** Between ADR and Sprint goal, try to think about it and ask the user to resolve the conflict. 54 | 55 | **If no ADRs found:** Proceed but note that tasks may need clarification during implementation. 56 | 57 | ### 4. Analyze sprint deliverables for task breakdown 58 | 59 | Based on sprint goals and deliverables (execute in Parallel Subagents): 60 | 61 | - BREAK DOWN high-level deliverables into concrete, implementable tasks 62 | - ENSURE each task represents a coherent feature or component 63 | - CONSIDER logical dependencies between tasks 64 | - MAP tasks to relevant ADRs for technical guidance 65 | - DEFER complexity assessment until after tasks are fully created with subtasks 66 | 67 | ### 5. Create individual task files with implementation guidance 68 | 69 | **NOW** For each identified Task spin up a Parallel Subagent with these Instructions: 70 | 71 | #### Create a TODO for EACH task 72 | 73 | 1. Create basic task structure 74 | 2. Research codebase interfaces 75 | 3. Add technical guidance 76 | 4. Validate task completeness 77 | 78 | ### 1. Create basic task structure 79 | 80 | - ALL TASK FILES must to be created in the Sprint Directory (where the sprint meta file is) 81 | - CREATE file with naming: `T<NN>_S<NN>_<Descriptive_Name>.md` 82 | - USE sequential numbering starting from T01 83 | - FOLLOW task template structure exactly from `.simone/99_TEMPLATES/task_template.md` 84 | - ADD basic description and objectives from sprint goals 85 | 86 | ### 2. Research codebase interfaces 87 | 88 | - EXAMINE existing codebase for similar patterns and interfaces 89 | - IDENTIFY specific classes, functions, and imports that will be needed 90 | - FIND integration points with existing modules 91 | - NOTE database models, API endpoints, or services to interface with 92 | - CHECK existing error handling and logging patterns 93 | 94 | ### 3. Add technical guidance 95 | 96 | Add these sections to the task file (add to template if not present): 97 | 98 | **Technical Guidance section:** 99 | 100 | - Key interfaces and integration points in the codebase 101 | - Specific imports and module references 102 | - Existing patterns to follow 103 | - Database models or API contracts to work with 104 | - Error handling approach used in similar code 105 | 106 | **Implementation Notes section:** 107 | 108 | - Step-by-step implementation approach 109 | - Key architectural decisions to respect 110 | - Testing approach based on existing test patterns 111 | - Performance considerations if relevant 112 | 113 | **IMPORTANT:** Do NOT include code examples. Provide structural guidance and references only. 114 | 115 | #### 4. Validate task completeness 116 | 117 | - ENSURE task has clear implementation path 118 | - VERIFY all integration points are documented 119 | - CHECK that guidance references actual codebase elements 120 | - CONFIRM task is self-contained and actionable 121 | 122 | **REPEAT** `### 5. Create individual task files with implementation guidance` for every Task 123 | 124 | ### 6. Link ADRs to relevant tasks 125 | 126 | - IF relevant ADRs exist 127 | - REFERENCE ADRs that are related 128 | - ADD explanation in Technical Guidance section for how each ADR applies 129 | - ENSURE tasks ONLY reference ADRs that affect their implementation 130 | 131 | ### 7. Update sprint meta with task references 132 | 133 | - EDIT sprint meta file to add/update task list 134 | - ORGANIZE tasks by logical grouping or dependency order 135 | - ADD brief description for each task 136 | 137 | ### 8. Check quality of your work 138 | 139 | Review all created tasks for complexity and split any High complexity tasks: 140 | 141 | **Complexity Assessment Process:** 142 | 143 | - READ each task file completely including description, goals, acceptance criteria, and subtasks 144 | - ASSESS complexity using your judgment about the overall scope and challenge 145 | - DO NOT base complexity on simple metrics like file counts or estimated hours 146 | - CONSIDER the conceptual difficulty, integration challenges, and unknowns 147 | - MARK complexity as Low, Medium, or High in the task frontmatter 148 | 149 | **If ANY task is marked as High complexity:** 150 | 151 | - SPLIT the task into 2-3 smaller tasks of Low or Medium complexity 152 | - CREATE new task files with proper sequential numbering 153 | - UPDATE the original high-complexity task file or DELETE it 154 | - ENSURE the split tasks together achieve the original goal 155 | - MAINTAIN logical grouping and dependencies 156 | 157 | **After all tasks are finalized:** 158 | 159 | - VERIFY all tasks are Low or Medium complexity only 160 | - CHECK task numbering is sequential (T01, T02, T03...) 161 | - UPDATE sprint meta file with final task list 162 | - UPDATE project manifest sprint section to reflect actual tasks created 163 | - GENERATE completion report 164 | 165 | **Output format:** 166 | 167 | ```Markdown 168 | ## Sprint Detailed - [YYYY-MM-DD HH:MM] 169 | 170 | **Sprint:** [Sprint ID] - [Sprint Name] 171 | **Status:** Planning Complete 172 | 173 | **Tasks Created:** [final count after any splits] 174 | - Medium Complexity: [count] 175 | - Low Complexity: [count] 176 | 177 | **Task Splitting Summary:** 178 | - [Original T03 split into T03 and T04 due to scope] 179 | - [No other splits needed] 180 | 181 | **Final Task List:** 182 | 1. T01_S02 - [Title] (Complexity: [Level]) 183 | 2. T02_S02 - [Title] (Complexity: [Level]) 184 | [Continue for all tasks] 185 | 186 | **Next Steps:** 187 | - Review tasks for completeness 188 | - Run `/do_task [FIRST_TASK_IN_SPRINT]` to begin implementation 189 | ``` 190 | -------------------------------------------------------------------------------- /.claude/commands/simone/create_sprints_from_milestone.md: -------------------------------------------------------------------------------- 1 | # Plan Sprints from a given Milestone. Execute from Top to Bottom 2 | 3 | Follow these instructions to sprint the scope of a Milestone into Sprints 4 | 5 | ## Create a TODO with EXACTLY these 8 items 6 | 7 | 1. Analyze current milestone state 8 | 2. Assess completed work vs milestone requirements 9 | 3. Identify remaining work and dependencies 10 | 4. Design logical sprint boundaries 11 | 5. Create sprint directories and meta files 12 | 6. Update PROJECT_MANIFEST with sprint roadmap 13 | 7. Validate sprint coherence and dependencies 14 | 8. Report milestone plan 15 | 16 | --- 17 | 18 | ## 1 · Analyze current milestone state 19 | 20 | **CRITICAL:** You are given additional Arguments: <$ARGUMENTS> 21 | 22 | **USE PARALLEL SUBAGENTS** to do these tasks: 23 | 24 | - Parse arguments for milestone ID (defaults to current milestone from PROJECT_MANIFEST) 25 | - Read `.simone/00_PROJECT_MANIFEST.md` to understand current progress 26 | - Scan `.simone/03_SPRINTS/` to identify existing sprints for the target milestone 27 | - For each existing sprint, read its sprint meta file to determine status from YAML frontmatter 28 | - Analyze the Tasks in Sprints to understand that work that has been done (from Subtasks) 29 | 30 | ## 2 · Assess completed work vs milestone requirements 31 | 32 | - Read milestone meta file from `.simone/02_REQUIREMENTS/$MILESTONE_ID/` 33 | - **CRITICAL:** Follow and read ALL linked documents in the milestone meta: 34 | - Product Requirements (PRD.md) 35 | - Database Specifications (SPECS_DB.md) 36 | - API Specifications (SPECS_API.md) 37 | - Tool Specifications (SPECS_TOOLS.md) 38 | - Any other linked specifications 39 | - Study the milestone's Definition of Done (DoD) carefully and **think deeply** about what each DoD criterion actually requires in terms of specific deliverables 40 | - For each existing sprint, analyze what deliverables have been completed by reading sprint meta and task files 41 | - **Think more carefully** about the gap analysis: map each completed deliverable against specific DoD requirements and identify what's genuinely missing vs what might already be covered 42 | - Create clear picture: "What's done vs what's required for milestone completion" with specific justification for each gap identified 43 | 44 | ## 3 · Identify remaining work and dependencies 45 | 46 | - Based on gap analysis, identify remaining deliverables for milestone completion 47 | - Group related deliverables that have natural dependencies 48 | - **CRITICAL:** Each deliverable group should be: 49 | - **Independently valuable** (shippable increment) 50 | - **Completable in ~1 week** by one person 51 | - **Has clear validation criteria** 52 | - Consider technical dependencies (e.g., auth before UI, LLM integration before tools) 53 | 54 | ## 4 · Design logical sprint boundaries 55 | 56 | - Design sprint structure to complete the milestone 57 | - Each sprint should have: 58 | - **Clear focus**: One main deliverable theme 59 | - **Natural boundaries**: Minimal dependencies between sprints 60 | - **Incremental value**: Each sprint advances toward milestone DoD 61 | - Sprint naming: `S<nn>_$milestone_id_$focus_slug` 62 | - **IMPORTANT:** Don't create sprints for work that's already completed 63 | 64 | ## 5 · Create sprint directories and meta files 65 | 66 | - For each planned sprint that doesn't exist: 67 | - Create directory `.simone/03_SPRINTS/$FULL_SPRINT_NAME/` (using complete sprint name like "S02_M01_LLM_Integration") 68 | - Use template from `.simone/99_TEMPLATES/sprint_meta_template.md` 69 | - Fill in sprint meta with: 70 | - High-level goal and scope 71 | - Key deliverables (bullet points, not detailed tasks) 72 | - Clear Definition of Done for the sprint 73 | - Status: "planned" 74 | 75 | ## 6 · Update PROJECT_MANIFEST with sprint roadmap 76 | 77 | - Update `.simone/00_PROJECT_MANIFEST.md`: 78 | - Set `highest_sprint_in_milestone` to the highest planned sprint 79 | - Update sprint summary section with overview of remaining sprints 80 | - Mark completed sprints as ✅ COMPLETED 81 | - Show planned sprints with their focus areas 82 | - Update `last_updated` timestamp 83 | 84 | ## 7 · Validate sprint coherence and dependencies 85 | 86 | - Review the planned sprint sequence for logical flow 87 | - Ensure each sprint builds naturally on previous work 88 | - Verify no sprint has impossible dependencies 89 | - Check that sprint sequence leads to milestone DoD completion 90 | - **Think about** whether each sprint is independently testable and valuable 91 | 92 | ## 8 · Report milestone plan 93 | 94 | Provide comprehensive summary: 95 | 96 | **Milestone Status:** 97 | 98 | - Target milestone: $milestone_id 99 | - Sprints completed: $count 100 | - Sprints planned: $count 101 | - Estimated completion: $sprint_sequence 102 | 103 | **Sprint Roadmap:** 104 | 105 | For each sprint (existing and planned): 106 | 107 | - **$Sprint_ID**: $status - $focus_description 108 | - Key deliverables: $bullet_list 109 | - Dependencies: $if_any 110 | 111 | **Next Steps:** 112 | 113 | - Immediate next sprint to detail: $sprint_id 114 | 115 | **Validation:** 116 | 117 | Summarize your validation analysis covering: 118 | 119 | - All milestone DoD items are covered by sprint plan 120 | - Sprint dependencies are logical and minimal 121 | - Each sprint delivers independent value 122 | -------------------------------------------------------------------------------- /.claude/commands/simone/discuss_review.md: -------------------------------------------------------------------------------- 1 | # Discuss Review Findings 2 | 3 | Engage in technical discussion about recent review findings based on discussion starter. 4 | 5 | Discussion Starter: <$ARGUMENTS> 6 | 7 | ## Discussion Primer 8 | 9 | **IMPORTANT:** Maintain John Carmack perspective - brutally honest, practical, focused on shipping working software. 10 | 11 | ### Discussion Tone 12 | 13 | - **Be conversational** but maintain technical depth 14 | - **Challenge assumptions** - question if issues are real problems for current development stage 15 | - **Explore trade-offs** - suggest multiple approaches with pros/cons 16 | - **Focus on decisions** - what to do next, not just analysis 17 | - **Consider context** - balance technical perfection vs delivery timeline 18 | 19 | ### Potential Discussion Outcomes 20 | 21 | Based on the conversation, you may suggest: 22 | 23 | - **Amending review findings** if new context changes severity/priority 24 | - **Updating documentation** in `.simone/01_PROJECT_DOCS/` if architectural decisions need clarification 25 | - **Revising requirements** in `.simone/02_REQUIREMENTS/` if scope understanding was incorrect 26 | - **Creating tasks** for specific technical debt items that need addressing 27 | - **Adjusting sprint priorities** based on refined understanding 28 | 29 | **IMPORTANT:** Help make practical engineering decisions. Be John Carmack: direct, experienced, and focused on what actually matters for shipping. 30 | -------------------------------------------------------------------------------- /.claude/commands/simone/do_task.md: -------------------------------------------------------------------------------- 1 | # Process Simone Task based on $Argument 2 | 3 | **IMPORTANT:** Follow from Top to Bottom - don't skip anything! 4 | 5 | **CREATE A TODO LIST** with exactly these 8 items 6 | 7 | 1. Analyse scope from argument 8 | 2. Identify task file 9 | 3. Analyse the task 10 | 4. Set status to in_progress 11 | 5. Execute task work 12 | 6. Placeholder 13 | 7. Execute Code review 14 | 8. Finalize Task status 15 | 16 | ## 1 · Analyse scope from argument 17 | 18 | <$ARGUMENTS> ⇒ Task ID, Sprint ID, or empty (select next open task in current sprint). 19 | 20 | ## 2 · Identify task file 21 | 22 | Search .simone/03_SPRINTS/ and .simone/04_GENERAL_TASKS/. 23 | If no open task matches, pause and ask the user how to proceed. 24 | 25 | ## 3 · Analyse the task 26 | 27 | Read the task description. If anything is unclear, ask clarifying questions before continuing. 28 | 29 | **CRITICAL CONTEXT VALIDATION:** Before executing any task spin up Parallel Subagents for these tasks: 30 | 31 | 1. **Sprint Context:** Confirm task belongs to current sprint scope 32 | 2. **Dependencies:** Check if any dependent tasks need to be completed first 33 | 3. **Requirements:** Read relevant requirements docs in `.simone/02_REQUIREMENTS/` 34 | 4. **Scope Verification:** Ensure task aligns with current sprint objectives 35 | 36 | **IMPORTANT:** If task references functionality from future sprints or has unmet dependencies, pause and ask for clarification. 37 | 38 | ## 4 · Set status to in_progress 39 | 40 | - Find out the current local timestamp (YYYY-MM-DD HH:MM). 41 | - Update front-matter to **status: in_progress** and set Updated time 42 | - Update ./simone/00_PROJECT_MANIFEST.md to set task in progress, updated time and current Sprint Status. 43 | 44 | ## 5 · Execute task work 45 | 46 | - Follow Description, Goal and Acceptance Criteria. 47 | - Consult supporting docs in .simone/01_PROJECT_DOCS/ and .simone/02_REQUIREMENTS/. 48 | - Iterate over subtasks: 49 | 1. Pick the next incomplete subtask. 50 | 2. Implement the required changes, consulting docs as needed. 51 | 3. Mark the subtask done. 52 | 4. Append a log entry to **## Output Log** using the format `[YYYY-MM-DD HH:MM]: <message>`. 53 | 5. Repeat until all subtasks are complete. 54 | 55 | ## 6 · Placeholder 56 | 57 | Placeholder - just move on to the next step 58 | 59 | ## 7 · Execute Code Review 60 | 61 | Follow these steps for a Code Review (in order) 62 | 63 | - include @.claude/commands/simone/code_review.md and use the Task ID as Scope. 64 | - Follow the instructions in the file to run a code review in **PARALLEL SUBAGENTS** 65 | - When done continue acting on the results accordingly 66 | - Understand and think about the results 67 | - on **FAIL** 68 | - thoroughly understand the problem 69 | - extend the Current Task with the Subtasks identified by the review 70 | - go back to "5 · Execute task work" 71 | - on **PASS** 72 | - move on to next step 73 | 74 | ## 8 · Finalize task status 75 | 76 | - set the Task status to **completed** 77 | - Rename the Task file accordingly to enable proper Completed recognition from the filename (TX[TASK_ID]...) 78 | - Update .simone/00_PROJECT_MANIFEST.md to reflect the new status 79 | - **Report** the result to the user 80 | 81 | ✅ **Result**: Quick statement of success 82 | 83 | 🔎 **Scope**: Identified task or reason none was processed 84 | 85 | 💬 **Summary**: One-paragraph recap of what was done or why blocked 86 | 87 | ⏭️ **Next steps**: Recommended follow-up actions 88 | 89 | - **Suggestions** for the User: 90 | 91 | - 🛠️ Use /project:simone:commit `TASK_ID` to commit the changes to git 92 | - 🧹 Use /clear to clear the context before starting the next Task 93 | -------------------------------------------------------------------------------- /.claude/commands/simone/initialize.md: -------------------------------------------------------------------------------- 1 | # Initialize Simone Framework 2 | 3 | Initialize the Simone project management framework through an adaptive, interactive process. 4 | 5 | ## Create a TODO with EXACTLY these items 6 | 7 | 1. Scan and analyze the project 8 | 2. Interactive confirmation with user 9 | 3. Check for existing Simone documents 10 | 4. Guide document creation process 11 | 5. Create first milestone for Simone 12 | 6. Generate project manifest 13 | 7. Provide next steps 14 | 15 | ## DETAILS on every TODO item 16 | 17 | ### 1. Scan and analyze the project 18 | 19 | **Detect project characteristics:** 20 | - Check for package.json, requirements.txt, composer.json, etc. 21 | - Identify project type (Node.js, Python, PHP, etc.) 22 | - Scan overall project structure 23 | - Check if this is a new or existing project 24 | - Look for existing documentation (README, docs/, etc.) 25 | 26 | **Keep findings brief** - Just identify the essentials 27 | 28 | ### 2. Interactive confirmation with user 29 | 30 | **Present findings conversationally:** 31 | ``` 32 | I found this to be a [project type] project named [detected name]. 33 | Is this correct? Should I proceed with Simone setup? 34 | ``` 35 | 36 | **Get user confirmation before continuing** 37 | 38 | ### 3. Check for existing Simone documents 39 | 40 | **Scan .simone/ directory for:** 41 | - Any documents in 01_PROJECT_DOCS/ 42 | - Any milestones in 02_REQUIREMENTS/ 43 | - Any existing sprints or tasks 44 | - Current manifest status 45 | 46 | **Interactive decision:** 47 | - If documents found: "I found existing documents: [list]. Should we work with these or extend them?" 48 | - If no documents: "No Simone documents found yet. Do you have any existing project documentation you'd like to copy in before we continue?" 49 | 50 | **Allow user to:** 51 | - Use existing documents 52 | - Add new documents 53 | - Start fresh 54 | - Cancel to add documents manually first 55 | 56 | ### 4. Guide document creation process 57 | 58 | **Based on user's choice:** 59 | 60 | **If starting fresh or extending:** 61 | - Perform deep analysis of the codebase 62 | - Identify key components and architecture patterns 63 | - Create draft ARCHITECTURE.md based on analysis 64 | - Use Q&A style to refine and complete: 65 | - "What's the main purpose of this project?" 66 | - "What are the key technical decisions?" 67 | - "Any important constraints or requirements?" 68 | 69 | **If using existing docs:** 70 | - Import and adapt existing documentation 71 | - Fill in any Simone-specific sections 72 | - Ensure compatibility with framework structure 73 | 74 | **Keep it conversational and adaptive** 75 | 76 | ### 5. Create first milestone for Simone 77 | 78 | **Determine appropriate first milestone:** 79 | - If new project: Start with setup/foundation milestone 80 | - If existing project: Identify current phase and create appropriate milestone 81 | 82 | **Interactive milestone creation:** 83 | - "Based on the project state, I suggest creating milestone: [name]" 84 | - "What would you like to focus on in this milestone?" 85 | - Create milestone structure with initial requirements 86 | - Keep scope realistic and focused 87 | 88 | ### 6. Generate project manifest 89 | 90 | **Automatically generate manifest using:** 91 | - Information gathered during setup 92 | - Created/imported documentation 93 | - Current milestone details 94 | - Project metadata 95 | 96 | **No user interaction needed** - Just inform when complete 97 | 98 | ### 7. Provide next steps 99 | 100 | **Customized guidance based on setup:** 101 | ``` 102 | ✅ Simone initialized for [project name]! 103 | 104 | Current setup: 105 | - Project type: [type] 106 | - Current milestone: [milestone] 107 | - Documents: [created/imported] 108 | 109 | Next steps: 110 | - Review your architecture: 01_PROJECT_DOCS/ARCHITECTURE.md 111 | - Check milestone requirements: 02_REQUIREMENTS/[milestone]/ 112 | - Start first task: /project:simone:create_general_task 113 | 114 | Ready to begin development! 115 | ``` 116 | 117 | ## ADAPTIVE PROCESS NOTES 118 | 119 | - **Stay conversational** - Ask questions naturally, not like a form 120 | - **Be smart** - Use AI to understand context and make intelligent suggestions 121 | - **Allow flexibility** - User can skip, cancel, or modify at any point 122 | - **Focus on value** - Only create what's useful for the specific project 123 | - **Keep it simple** - Don't overwhelm with options or details -------------------------------------------------------------------------------- /.claude/commands/simone/prime.md: -------------------------------------------------------------------------------- 1 | # Prime your knowledge 2 | 3 | Prime yourself with basic information about this project. 4 | Make sure you are aware of the environment. 5 | 6 | ## USE **PARALLEL AGENTS** to 7 | 8 | - READ .simone/01_PROJECT_DOCS/ARCHITECTURE.md for basic Project Information 9 | - READ .simone/00_PROJECT_MANIFEST.md for the Project status -------------------------------------------------------------------------------- /.claude/commands/simone/project_review.md: -------------------------------------------------------------------------------- 1 | # Project Review - Execute top to bottom 2 | 3 | Perform a comprehensive project-level review focusing on architecture, progress, and technical decisions. 4 | 5 | **IMPORTANT:** 6 | 7 | - This is a high-level review of overall project state, not recent changes. 8 | - Unless clearly mentioned in project documents, there is no timeline and schedule is irrelevant 9 | 10 | ## Create a TODO with EXACTLY these 9 Items 11 | 12 | 1. Analyze review scope and timing 13 | 2. Execute and assess test infrastructure health 14 | 3. Assess project documentation alignment 15 | 4. Review milestone and sprint progress 16 | 5. Analyze codebase architecture and structure 17 | 6. Audit file organization and workflow compliance 18 | 7. Evaluate technical decisions and complexity 19 | 8. Critique implementation quality (John Carmack perspective) 20 | 9. Provide comprehensive assessment with recommendations 21 | 22 | Follow step by step and adhere closely to the following instructions for each step. 23 | 24 | ## DETAILS on every TODO item 25 | 26 | ### 1. Analyze review scope and timing 27 | 28 | Check: <$ARGUMENTS> 29 | 30 | If empty, perform full project review. Otherwise interpret <$ARGUMENTS> to identify specific focus areas (milestone, sprint, architecture component, etc.). Unless stated in Argument do not compare to previews project reviews in `.simone/10_STATE_OF_PROJECT`. 31 | 32 | **IMPORTANT:** This review looks at overall project state in context of recent changes. 33 | 34 | **CRITICAL:** Read `.simone/00_PROJECT_MANIFEST.md` FIRST to understand: 35 | 36 | - Current milestone and sprint status 37 | - What work is complete vs in-progress vs planned 38 | - Active sprint objectives and deliverables 39 | 40 | **CONTEXT CHECK:** Before evaluating functionality: 41 | 42 | - Navigate to `.simone/03_SPRINTS/` to find the current sprint 43 | - Read the sprint meta file to understand what's in scope 44 | - Check completed vs planned tasks within the sprint 45 | - Understand what future sprints will deliver 46 | 47 | **REVIEW PRINCIPLE:** Evaluate against CURRENT SPRINT deliverables, not full milestone scope. 48 | 49 | ### 2. Execute and assess test infrastructure health 50 | 51 | **CRITICAL:** Test infrastructure health is a BLOCKING criteria for sprint/milestone progression. 52 | 53 | - USE test.md command to execute full test suite (@.claude/commands/simone/test.md) 54 | - ANALYZE test results: passed/failed/skipped counts and failure categories 55 | - CALCULATE test health score (0-10 scale): 56 | - 10: 100% pass rate, no infrastructure issues 57 | - 8-9: >95% pass rate, minor issues only 58 | - 6-7: 80-95% pass rate, some non-critical failures 59 | - 4-5: 60-80% pass rate, significant issues 60 | - 0-3: <60% pass rate, critical infrastructure problems 61 | - CATEGORIZE failures: 62 | - Infrastructure: Import errors, missing modules 63 | - Configuration: Environment variables, database connections 64 | - Logic: Assertion failures, actual bugs 65 | - Flaky: Intermittent failures 66 | - DETERMINE blocking status: 67 | - Score < 6: BLOCKS sprint progression 68 | - Score < 8: BLOCKS milestone completion 69 | - Score < 4: TRIGGERS emergency escalation 70 | - IDENTIFY root causes of any infrastructure failures 71 | - TRACK trend vs previous review (improvement/degradation) 72 | - ASSESS test strategy validity for scope of the project. Tests should be pragmatic and help assuring functionality but not get in the way of development progress too much. 73 | 74 | ### 3. Assess project documentation alignment 75 | 76 | **USE PARALLEL AGENTS** to follow these steps: 77 | 78 | - READ all core documents in `.simone/01_PROJECT_DOCS/` especially ARCHITECTURE.md 79 | - READ current milestone requirements in `.simone/02_REQUIREMENTS/` 80 | - READ architecture decisions in `.simone/05_ARCHITECTURE_DECISIONS` as they might extend/contradict other documents 81 | - IDENTIFY any gaps between documentation and current implementation 82 | - CHECK if the project is still following the documented architecture vision 83 | - VERIFY that current code structure matches documented patterns 84 | 85 | **IMPORTANT:** Documentation is our source of truth. Any deviation needs justification. 86 | 87 | ### 4. Review milestone and sprint progress 88 | 89 | **USE PARALLEL AGENTS** to follow these steps: 90 | 91 | - READ `.simone/00_PROJECT_MANIFEST.md` for current status 92 | - ANALYZE completed sprints in `.simone/03_SPRINTS/` 93 | - COMPARE actual progress against CURRENT SPRINT deliverables (not full milestone) 94 | - DISTINGUISH between sprint-level tasks vs milestone-level features 95 | - ASSESS if current sprint focus aligns with milestone goals 96 | 97 | ### 5. Analyze codebase architecture and structure 98 | # 99 | **USE PARALLEL AGENTS** to follow these steps: 100 | 101 | - EXAMINE overall project structure and organization 102 | - ANALYZE import patterns and dependency relationships 103 | - REVIEW database models and API structure for consistency 104 | - CHECK for architectural patterns: are we following DDD, clean architecture, etc.? 105 | - IDENTIFY any architectural debt or inconsistencies 106 | 107 | **Focus areas:** 108 | 109 | - **Directory structure** — logical organization, separation of concerns 110 | - **Dependencies** — are we over-engineering? unnecessary libraries? 111 | - **Models/Schemas** — consistency, proper relationships, normalization 112 | - **APIs** — RESTful design, proper HTTP methods, consistent patterns 113 | - **Configuration** — environment management, secrets handling 114 | 115 | ### 6. Audit file organization and workflow compliance 116 | 117 | **IMPORTANT:** Check for workflow discipline and architectural boundary violations. 118 | 119 | - **Root directory audit** — identify files that don't belong in project root 120 | - **Development scripts** — verify all dev scripts follow `run_dev.py` pattern 121 | - **Test file organization** — check tests are in `tests/` directory, not scattered 122 | - **Documentation placement** — verify docs are in proper locations 123 | - **Temporary/experimental files** — flag any `.py` files that look ad-hoc or experimental 124 | 125 | **File Organization Rules to Enforce:** 126 | 127 | - **Development scripts** — MUST go through `run_dev.py`, not standalone files 128 | - **Test files** — MUST be in `tests/` directory with proper naming (`test_*.py`) 129 | - **Documentation** — MUST be in `docs/` or `.simone/01_PROJECT_DOCS/` 130 | - **Configuration** — MUST follow established patterns (`.env.example`, `pyproject.toml`) 131 | - **Temporary files** — SHOULD NOT exist in committed code 132 | 133 | **Red Flags to Identify:** 134 | 135 | - Multiple scripts doing similar things (duplicate functionality) 136 | - Random `.py` files in root directory 137 | - Test files outside `tests/` directory 138 | - Development scripts bypassing `run_dev.py` 139 | - Unclear file purposes or experimental code 140 | 141 | **CRITICAL:** File proliferation indicates workflow breakdown. Flag for immediate cleanup task creation. 142 | 143 | ### 7. Evaluate technical decisions and complexity 144 | 145 | - ASSESS complexity vs. business value ratio 146 | - REVIEW choice of frameworks, libraries, and tools 147 | - ANALYZE if current patterns will scale with project growth 148 | - IDENTIFY areas where we might be over-complicating simple problems 149 | - CHECK for premature optimization or under-optimization 150 | 151 | **IMPORTANT:** Think like an experienced developer. Are we solving the right problems the right way? 152 | 153 | ### 8. Critique implementation quality (John Carmack perspective) 154 | 155 | Think as John Carmack would: focus on simplicity, performance, and maintainability, but keep the projects goal in mind. Especially long term vision as well. Don't over simplify. 156 | 157 | - **Simplicity:** Are we solving problems in the most straightforward way? 158 | - **Performance:** Are there obvious performance issues or bottlenecks? 159 | - **Maintainability:** Will a new developer understand this code in 6 months? 160 | - **Robustness:** How does the system handle edge cases and failures? 161 | - **Technical debt:** What shortcuts are we taking that will hurt us later? 162 | 163 | Be **brutally honest**. Carmack-level critique means no sugar-coating but still staying true to the project's reality. 164 | Be thorough and **go above and beyond** in your analysis - leave no stone unturned. 165 | 166 | ### 9. Provide comprehensive assessment with recommendations 167 | 168 | **IMPORTANT:** Get current timestamp and create output file 169 | 170 | - Get current timestamp using system date command 171 | - Create filename: `YYYY-MM-DD-HH-MM-<judgment-slug>.md` in `.simone/10_STATE_OF_PROJECT/` 172 | - Judgment slug should be 2-3 words describing overall project health (e.g., "solid-progress", "needs-focus", "critical-issues", "doing-great", "on-track") 173 | 174 | **IMPORTANT:** Write full report to the timestamped file with this format: 175 | 176 | ```markdown 177 | # Project Review - [YYYY-MM-DD HH:MM] 178 | 179 | ## 🎭 Review Sentiment 180 | 181 | [3 emojis only - no explanations] 182 | 183 | ## Executive Summary 184 | 185 | - **Result:** EXCELLENT | GOOD | NEEDS_WORK | CRITICAL_ISSUES 186 | - **Scope:** What areas were reviewed 187 | - **Overall Judgment:** [2-3 word assessment used in filename] 188 | 189 | ## Test Infrastructure Assessment 190 | 191 | - **Test Suite Status**: [PASSING/FAILING/BLOCKED] (X/Y tests) 192 | - **Test Pass Rate**: X% (Y passed, Z failed) 193 | - **Test Health Score**: X/10 194 | - **Infrastructure Health**: [HEALTHY/DEGRADED/BROKEN] 195 | - Import errors: [count] 196 | - Configuration errors: [count] 197 | - Fixture issues: [count] 198 | - **Test Categories**: 199 | - Unit Tests: X/Y passing 200 | - Integration Tests: X/Y passing 201 | - API Tests: X/Y passing 202 | - **Critical Issues**: 203 | - [List of blocking test infrastructure problems] 204 | - [Module import mismatches] 205 | - [Environment configuration failures] 206 | - **Sprint Coverage**: [% of sprint deliverables with passing tests] 207 | - **Blocking Status**: [CLEAR/BLOCKED - reason] 208 | - **Recommendations**: 209 | - [Immediate fixes required] 210 | - [Test infrastructure improvements needed] 211 | 212 | ## Development Context 213 | 214 | - **Current Milestone:** [ID and status from manifest] 215 | - **Current Sprint:** [ID and focus] 216 | - **Expected Completeness:** [what SHOULD be done at this stage] 217 | 218 | ## Progress Assessment 219 | 220 | - **Milestone Progress:** [percentage complete] 221 | - **Sprint Status:** [current sprint assessment] 222 | - **Deliverable Tracking:** [what's done vs planned] 223 | 224 | ## Architecture & Technical Assessment 225 | 226 | - **Architecture Score:** 1-10 rating with explanation 227 | - **Technical Debt Level:** LOW | MEDIUM | HIGH with specific examples 228 | - **Code Quality:** [overall assessment with examples] 229 | 230 | ## File Organization Audit 231 | 232 | - **Workflow Compliance:** GOOD | NEEDS_ATTENTION | CRITICAL_VIOLATIONS 233 | - **File Organization Issues:** [list any misplaced files, duplicate scripts, etc.] 234 | - **Cleanup Tasks Needed:** [specific file moves/deletions/consolidations required] 235 | 236 | ## Critical Findings 237 | ### Critical Issues (Severity 8-10) 238 | 239 | [Lists of must-fix problems headed with #### heading, one empty line and then list of details] 240 | 241 | ### Improvement Opportunities (Severity 4-7) 242 | 243 | [List of recommended enhancements headed with #### heading, one empty line and then list of details] 244 | 245 | ## John Carmack Critique 🔥 246 | 247 | [Top 3 brutally honest observations about technical decisions] 248 | 249 | ## Recommendations 250 | 251 | Based on your findings recommend Action items - chose whatever fits your findings 252 | 253 | - **Important fixes:** What needs to be fixed immediately? 254 | - **Optional fixes/changes:** What would still be recommended though optional? 255 | - **Next Sprint Focus:** Can the user move to the next sprint? 256 | 257 | ``` 258 | 259 | **IMPORTANT:** Be specific with file paths and line numbers. This review should be actionable and permanently archived. 260 | -------------------------------------------------------------------------------- /.claude/commands/simone/test.md: -------------------------------------------------------------------------------- 1 | # Run tests and fix common issues 2 | 3 | Follow these instructions from top to bottom. 4 | 5 | ## Create a TODO with EXACTLY these 4 items 6 | 7 | 1. Execute test suite 8 | 2. Analyze results and identify issues 9 | 3. Fix common problems if found 10 | 4. Provide test summary 11 | 12 | --- 13 | 14 | ## 1 · Execute test suite 15 | 16 | ### First, detect the project's test runner: 17 | 18 | 1. **Python projects:** 19 | - If `pyproject.toml` exists with `[tool.poetry]`: Try `poetry run pytest` 20 | - If `setup.py` or `requirements.txt`: Try `pytest` or `python -m pytest` 21 | - If custom test script exists (e.g., `run_tests.py`, `run_dev.py`): Use that 22 | - Add common flags: `--tb=short` for pytest 23 | 24 | 2. **JavaScript/TypeScript projects:** 25 | - If `package.json` exists: Check "scripts" section for "test" command 26 | - Common: `npm test`, `npm run test`, `yarn test`, `pnpm test` 27 | - Framework specific: `jest`, `vitest`, `mocha` 28 | 29 | 3. **Other languages:** 30 | - Rust: `cargo test` 31 | - Go: `go test ./...` 32 | - Java: `mvn test` or `gradle test` 33 | - Ruby: `bundle exec rspec` or `rake test` 34 | - PHP: `composer test` or `phpunit` 35 | 36 | ### Execute the detected test command: 37 | 38 | - RUN the appropriate test command 39 | - CAPTURE full output including any errors 40 | - NOTE execution time and test counts 41 | 42 | **If no test runner is found:** Report this to the user and ask for the correct test command. 43 | 44 | ## 2 · Analyze results and identify issues 45 | 46 | Check for common issues in this order: 47 | 48 | ### Language-specific issues: 49 | 50 | **Python:** 51 | - Missing __init__.py files (import errors, tests not discovered) 52 | - Import path problems 53 | - Fixture issues (pytest) 54 | - Virtual environment problems 55 | 56 | **JavaScript/TypeScript:** 57 | - Module resolution errors 58 | - Missing dependencies in node_modules 59 | - Jest/Vitest configuration issues 60 | - TypeScript compilation errors 61 | 62 | **Common across languages:** 63 | - Environment variable issues (missing config) 64 | - Database/external service connection errors 65 | - File path problems (absolute vs relative) 66 | - Permission issues 67 | 68 | ## 3 · Fix common problems if found 69 | 70 | **ONLY** fix these specific issues automatically:** 71 | 72 | ### Python-specific fixes: 73 | - CREATE empty `__init__.py` files where needed 74 | - FIX simple import path issues 75 | - ADD missing test directory to Python path if needed 76 | 77 | ### JavaScript/TypeScript fixes: 78 | - RUN `npm install` if node_modules missing 79 | - FIX simple module resolution in jest.config.js 80 | - CREATE missing test setup files 81 | 82 | ### General fixes: 83 | - CREATE missing test directories 84 | - FIX file permissions if possible 85 | - IDENTIFY missing env vars and inform user 86 | 87 | **DO NOT** fix: 88 | - Actual test logic failures 89 | - Business logic bugs 90 | - Complex configuration issues 91 | - Database schema problems 92 | - External service dependencies 93 | 94 | ## 4 · Provide test summary 95 | 96 | Create a brief summary: 97 | 98 | ``` 99 | Test Results: 100 | - Total: X tests 101 | - Passed: Y (Z%) 102 | - Failed: A 103 | - Skipped: B 104 | - Time: C seconds 105 | 106 | Issues Fixed: 107 | - [List any fixes applied] 108 | 109 | Issues Found (requires manual fix): 110 | - [List problems that need attention] 111 | 112 | Status: PASSING | FAILING | BLOCKED 113 | ``` 114 | 115 | **IMPORTANT:** Keep it concise. This command should be quick and focused on running tests, not detailed analysis. 116 | EOF < /dev/null 117 | -------------------------------------------------------------------------------- /.claude/commands/simone/testing_review.md: -------------------------------------------------------------------------------- 1 | # Testing Review - Execute top to bottom 2 | 3 | Analyzes test implementation against the project's testing strategy to ensure tests remain balanced, purposeful, and aligned with development goals. 4 | 5 | ## Prerequisites Check 6 | 7 | **FIRST**, check if a testing strategy document exists: 8 | - CHECK for `.simone/01_PROJECT_DOCS/TESTING_STRATEGY.md` 9 | - If NOT found, inform the user: "No testing strategy document found. Would you like me to help create one, or proceed with a general test quality review?" 10 | - If user wants to proceed without strategy, adapt the review to focus on general test quality principles 11 | 12 | ## Create a TODO with EXACTLY these 7 Items 13 | 14 | 1. Load testing strategy document (or define review criteria) 15 | 2. Analyze test implementation structure 16 | 3. Evaluate test-to-code alignment 17 | 4. Identify misaligned or unnecessary tests 18 | 5. Assess critical functionality coverage 19 | 6. Generate modification recommendations 20 | 7. Create alignment report 21 | 22 | Follow step by step and adhere closely to the following instructions for each step. 23 | 24 | ## DETAILS on every TODO item 25 | 26 | ### 1. Load testing strategy document (or define review criteria) 27 | 28 | **Option A - Strategy document exists:** 29 | - LOAD `.simone/01_PROJECT_DOCS/TESTING_STRATEGY.md` 30 | - EXTRACT key principles and priorities 31 | - IDENTIFY what should and shouldn't be tested 32 | - NOTE coverage expectations and quality gates 33 | - UNDERSTAND the testing philosophy 34 | 35 | **Option B - No strategy document:** 36 | Use general best practices as review criteria: 37 | - Tests should focus on behavior, not implementation 38 | - Critical paths must have coverage 39 | - Tests should be maintainable and clear 40 | - Avoid over-testing simple getters/setters 41 | - Balance between coverage and maintenance burden 42 | 43 | **DOCUMENT** which approach is being used for this review. 44 | 45 | ### 2. Analyze test implementation structure 46 | 47 | **EXAMINE** the current test codebase: 48 | 49 | - USE test.md command to run tests 50 | - EXPLORE test directory structure and organization 51 | - IDENTIFY test categories and their purposes 52 | - CHECK test naming conventions and patterns 53 | - NOTE any test infrastructure or utilities 54 | 55 | **Focus on understanding what exists, not counting.** 56 | 57 | ### 3. Evaluate test-to-code alignment 58 | 59 | **COMPARE** tests against actual implementation: 60 | 61 | - For each major component, check if tests match functionality 62 | - IDENTIFY tests that test implementation details vs behavior 63 | - FIND tests with excessive setup or mocking 64 | - LOCATE tests that break frequently on refactoring 65 | - CHECK if test complexity matches code complexity 66 | 67 | **Key question:** Do the tests validate what users care about? 68 | 69 | ### 4. Identify misaligned or unnecessary tests 70 | 71 | **SEARCH** for tests that don't provide value: 72 | 73 | **If using strategy document:** 74 | - Tests for areas marked as "skip" in strategy 75 | - Tests outside the defined scope 76 | - Over-specified tests per strategy guidelines 77 | 78 | **If using general principles:** 79 | - Over-engineered tests for simple functionality 80 | - Tests that break on every refactor 81 | - Edge case tests for non-critical features 82 | - Tests with excessive mocking/setup 83 | - Performance tests without performance requirements 84 | 85 | **Create a list of specific tests to modify or remove.** 86 | 87 | ### 5. Assess critical functionality coverage 88 | 89 | **VERIFY** that essential functionality has appropriate tests: 90 | 91 | **If using strategy document:** 92 | - CHECK coverage of high-priority areas defined in strategy 93 | - VERIFY strategy-specific requirements are tested 94 | 95 | **For all reviews:** 96 | - IDENTIFY gaps in critical path testing 97 | - CHECK authentication/authorization if applicable 98 | - VERIFY error handling for important operations 99 | - ENSURE data integrity tests exist where needed 100 | - CONFIRM integration points are tested 101 | 102 | **Note specific gaps that need addressing.** 103 | 104 | ### 6. Generate modification recommendations 105 | 106 | **CREATE** specific, actionable recommendations: 107 | 108 | For each finding: 109 | - SPECIFY the test file and function 110 | - EXPLAIN why it needs modification 111 | - SUGGEST the specific change (remove, simplify, add) 112 | - PROVIDE example of the improved approach if helpful 113 | 114 | **Format:** 115 | ``` 116 | File: tests/test_example.py::test_function_name 117 | Issue: [What's wrong] 118 | Action: [What to do] 119 | Reason: [Why this aligns with strategy] 120 | ``` 121 | 122 | ### 7. Create alignment report 123 | 124 | **GENERATE** a focused report on test-strategy alignment: 125 | 126 | - Get current timestamp using system date command 127 | - Create report in `.simone/10_STATE_OF_PROJECT/YYYY-MM-DD-HH-MM-test-alignment.md` 128 | 129 | **Report structure:** 130 | ```markdown 131 | # Test-Strategy Alignment Review - [YYYY-MM-DD HH:MM] 132 | 133 | ## Alignment Summary 134 | 135 | Overall alignment with testing strategy: [EXCELLENT | GOOD | NEEDS WORK | POOR] 136 | 137 | Key findings: 138 | - [Major finding about test suite health] 139 | - [Major finding about coverage] 140 | - [Major finding about maintenance burden] 141 | 142 | ## Tests Requiring Modification 143 | 144 | ### Remove (Over-engineered/Out of scope) 145 | [List specific tests with reasons] 146 | 147 | ### Simplify (Too complex for purpose) 148 | [List specific tests with simplification approach] 149 | 150 | ### Add (Critical gaps) 151 | [List specific missing tests for critical paths] 152 | 153 | ## Recommended Actions 154 | 155 | ### Immediate (Blocking issues) 156 | - [ ] [Specific action with file/test reference] 157 | 158 | ### Short-term (Quality improvements) 159 | - [ ] [Specific action with file/test reference] 160 | 161 | ### Long-term (Technical debt) 162 | - [ ] [Specific action with file/test reference] 163 | 164 | ## Test Health Indicators 165 | 166 | - Tests align with code purpose: [YES | PARTIALLY | NO] 167 | - Critical paths covered: [YES | PARTIALLY | NO] 168 | - Maintenance burden reasonable: [YES | PARTIALLY | NO] 169 | - Tests support development velocity: [YES | PARTIALLY | NO] 170 | 171 | ## Implementation Examples 172 | 173 | [If needed, show before/after examples of test improvements] 174 | 175 | ## Next Review 176 | 177 | Recommended review in: [X weeks/sprints] 178 | Focus areas for next review: [Specific areas to monitor] 179 | ``` 180 | 181 | **IMPORTANT:** Focus on alignment and balance, not metrics. The goal is tests that serve the project's actual needs. 182 | -------------------------------------------------------------------------------- /.claude/commands/simone/yolo.md: -------------------------------------------------------------------------------- 1 | # Execute all open tasks in YOLO mode 2 | 3 | This mode is meant to be run without user interaction. 4 | You **DO NOT** ask the user any questions or ask for confirmation 5 | If in doubt you **RESEARCH** and **ULTRATHINK** about the best solution. 6 | 7 | **IMPORTANT** you try not to stop at any certain point but do so if you need after thoughtful consideration. 8 | 9 | Priority is to get the work completed. 10 | 11 | ## Mode Selection 12 | 13 | Check <$ARGUMENTS>: 14 | 15 | - If sprint ID provided (e.g., S03): Work ONLY on that sprint 16 | - If empty: Work on general tasks first, then active sprint tasks 17 | 18 | **Report Mode** to the User! 19 | 20 | ## Safety Guidelines 21 | 22 | - **NEVER** modify critical files (.env, alembic migrations, production configs) 23 | - **STOP** if you encounter database schema changes 24 | - **STOP** if you need to delete more than 5 files 25 | - **STOP** if tests are failing after your changes 26 | - **ALWAYS** run tests after implementing a task 27 | 28 | ## Follow this exact process 29 | 30 | You need to stick to this process and **PRECISELY** follow it 31 | 32 | Before you start: 33 | 34 | - Run tests to ensure clean baseline using test.md command (@.claude/commands/simone/test.md) 35 | - **If** FAIL rate is above 10% asses if a fix is possible. If so, fix and move on. If not, move on anyways. 36 | 37 | - Check git status to ensure clean working directory 38 | - **If** git status is not clean just remember and report to the user at the end, but move on. 39 | 40 | Also consider <$ARGUMENTS> - if anything between <> can be considered additional instructions, prioritize them in the process. 41 | 42 | Get the current datetime stamp from the system and remember it 43 | 44 | ### FIND OPEN WORK 45 | 46 | Execute based on mode: 47 | 48 | **If Sprint ID provided in arguments:** 49 | 50 | - Navigate to .simone/03_SPRINTS/{sprint_id}/ 51 | - Check if sprint has tasks (T*.md files) 52 | - If NO tasks exist: 53 | - Check for sprint meta file 54 | - If meta exists: Jump to ### CREATE SPRINT TASKS 55 | - If no meta: Exit with error - sprint doesn't exist 56 | - If tasks exist: Continue to **Task selection** section below 57 | 58 | **If NO arguments (general mode):** 59 | 60 | - Use PARALLEL SUBAGENTS to check: 61 | - .simone/04_GENERAL_TASKS for open general tasks 62 | - .simone/00_PROJECT_MANIFEST.md for currently active sprint 63 | - .simone/03_SPRINTS/ for any sprint with only meta file 64 | - Priority order: 65 | 1. General tasks (if any open) 66 | 2. Active sprint tasks (if any open) 67 | 3. Sprint needing task creation (if found) - maintain order of Sprints 68 | 69 | **Task Selection:** 70 | 71 | - From found tasks, select ONE that is not completed. Take the lowest ID in Sprint or General Tasks 72 | - Skip tasks you've previously attempted (check OUTPUT LOG) 73 | - If no suitable task found and no sprint needs tasks: Exit gracefully 74 | 75 | ### CREATE SPRINT TASKS 76 | 77 | **ONLY EXECUTE** if sprint needs task creation 78 | 79 | - Use a **SUBAGENT** and have it include @.claude/commands/simone/create_sprint_tasks.md with Sprint ID as argument 80 | - Wait for completion 81 | - After task creation move back to `### FIND OPEN WORK` 82 | 83 | ### WORK ON TASK 84 | 85 | - if you have touched this task before ignore it and jump to the next task 86 | - if you can't find a task that you have not tried fixing before jump to ### EXECUTE PROJECT REVIEW 87 | - if you find a task that you cannot fix because the work was done already, close the task and note in Output Log of task. 88 | - **BEFORE STARTING**: Create a git branch for the task: `git checkout -b task/<task-id>` 89 | - **USE A SUBAGENT** and have it include @.claude/commands/simone/do_task.md with the Task ID as Argument to execute the Task. 90 | - **AFTER TASK COMPLETION**: Run tests to verify nothing broke using test.md command (@.claude/commands/simone/test.md) 91 | - on any failure in the task execution assess the severity of the error: 92 | - CRITICAL errors (breaking tests, security issues, data loss risk): **FIX PROBLEMS** 93 | - NON-CRITICAL errors (linting, formatting, minor issues): note in OUTPUT LOG and continue 94 | - on success move on 95 | 96 | ### COMMIT WORK 97 | 98 | - **ONLY IF** tests are passing and no critical issues exist 99 | - **USE A SUBAGENT** and have it include @.claude/commands/simone/commit.md with the Task ID as Argument and YOLO as additional argument 100 | - on any failure when committing, note the problem in the OUTPUT LOG of the task and continue 101 | - after successful commit, merge to main: `git checkout main && git merge task/<task-id>` 102 | - on success move on 103 | 104 | ### REPEAT FOR ALL OPEN TASKS 105 | 106 | **Based on current mode:** 107 | 108 | **Sprint-specific mode:** 109 | 110 | - Continue with next task in the specified sprint only 111 | - Go back to ### WORK ON TASK until all sprint tasks are done 112 | - When sprint is complete, move to project review 113 | 114 | **General mode:** 115 | 116 | - After completing a general task, check for more general tasks first 117 | - If no general tasks remain, move to active sprint tasks 118 | - Continue until all accessible tasks are done 119 | - When done move on 120 | 121 | ## EXECUTE PROJECT REVIEW 122 | 123 | - **USE A SUBAGENT** and have it include @.claude/commands/simone/project_review.md 124 | - Depending on the results of the review: 125 | - On FAIL: Think about possible fixes. 126 | - If fixes are quickly done, fix right away and repeat `## EXECUTE PROJECT REVIEW`` 127 | - If fixes are more complex **USE A SUBAGENT** and have it include @.claude/commands/simone/create_general_task.md to create new general tasks as needed. 128 | - Go back to `### FIND OPEN WORK` to work on these fixes 129 | - On PASS: move on 130 | 131 | ## MORE WORK TO DO? 132 | 133 | **Based on current mode:** 134 | 135 | **Sprint-specific mode:** 136 | 137 | Your work is done. Move to `## CREATE SUMMARY` 138 | 139 | **General mode:** 140 | 141 | - Move on to check for more open Tasks or Sprints. Move to `### FIND OPEN WORK` 142 | 143 | ## CREATE SUMMARY 144 | 145 | - Get current datetime stamp from the system and compare to initially remembered timestamp. Calculate duration of the process. 146 | - Create a summary report including: 147 | - Mode executed (Sprint-specific or General) 148 | - Sprint tasks created (if applicable) 149 | - Number of tasks completed 150 | - Number of tasks skipped/failed 151 | - Total duration 152 | - Any critical issues encountered 153 | - Current test status 154 | - Next recommended action 155 | - Report the result of the review to the user including the duration. 156 | 157 | Your work is done. Thank you. 158 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # OS generated files 2 | .DS_Store 3 | .DS_Store? 4 | ._* 5 | .Spotlight-V100 6 | .Trashes 7 | ehthumbs.db 8 | Thumbs.db 9 | 10 | # Root level files (except specific allowed files) 11 | /* 12 | !/.simone 13 | !/.claude 14 | !/.gitignore 15 | !/README.md 16 | !/LICENSE 17 | !/SYNC_GUIDE.md 18 | !/sync-simone.sh 19 | !/CHANGELOG.md 20 | 21 | # Editor directories and files 22 | .cursor/ 23 | .idea 24 | .vscode/* 25 | !.vscode/extensions.json 26 | !.vscode/settings.json 27 | *.swp 28 | *.swo 29 | *~ 30 | 31 | # Python 32 | __pycache__/ 33 | *.py[cod] 34 | *$py.class 35 | *.so 36 | .Python 37 | env/ 38 | venv/ 39 | .env 40 | 41 | # Node 42 | node_modules/ 43 | npm-debug.log* 44 | yarn-debug.log* 45 | yarn-error.log* 46 | 47 | # Logs 48 | *.log 49 | 50 | # Folders 51 | mixed_notes 52 | -------------------------------------------------------------------------------- /.simone/00_PROJECT_MANIFEST.md: -------------------------------------------------------------------------------- 1 | --- 2 | project_name: Your Project Name 3 | current_milestone_id: M01 4 | highest_sprint_in_milestone: S02 5 | current_sprint_id: S01 6 | status: active 7 | last_updated: 2025-01-01 00:00:00 8 | --- 9 | 10 | # Project Manifest: Your Project Name 11 | 12 | This manifest serves as the central reference point for the project. It tracks the current focus and links to key documentation. 13 | 14 | ## 1. Project Vision & Overview 15 | 16 | [Describe your project's core vision, purpose, and goals here. What problem does it solve? Who is it for? What makes it unique?] 17 | 18 | This project follows a milestone-based development approach. 19 | 20 | ## 2. Current Focus 21 | 22 | - **Milestone:** M01 - [Your First Milestone Name] 23 | - **Sprint:** S01 - [Current Sprint Focus] 24 | 25 | ## 3. Sprints in Current Milestone 26 | 27 | ### S01 [Sprint Name] (🚧 IN PROGRESS) 28 | 29 | 🚧 [First deliverable or feature] 30 | 📋 [Second deliverable or feature] 31 | 📋 [Third deliverable or feature] 32 | 33 | ### S02 [Sprint Name] (📋 PLANNED) 34 | 35 | 📋 [First planned deliverable] 36 | 📋 [Second planned deliverable] 37 | 📋 [Third planned deliverable] 38 | 39 | ## 4. Key Documentation 40 | 41 | - [Architecture Documentation](./01_PROJECT_DOCS/ARCHITECTURE.md) 42 | - [Current Milestone Requirements](./02_REQUIREMENTS/M01_[Milestone_Name]/) 43 | - [General Tasks](./04_GENERAL_TASKS/) 44 | 45 | ## 5. Quick Links 46 | 47 | - **Current Sprint:** [S01 Sprint Folder](./03_SPRINTS/S01_M01_[Sprint_Name]/) 48 | - **Active Tasks:** Check sprint folder for T##_S01_*.md files 49 | - **Project Reviews:** [Latest Review](./10_STATE_OF_PROJECT/) 50 | -------------------------------------------------------------------------------- /.simone/01_PROJECT_DOCS/ARCHITECTURE.md: -------------------------------------------------------------------------------- 1 | # Demo Project Architecture (EXAMPLE) 2 | 3 | This document outlines the high-level architecture of the Demo Project. **This is an example document to demonstrate how architecture might be documented in the Simone framework.** 4 | 5 | ## System Overview 6 | 7 | This is a demonstration of how a system architecture document might be structured. In a real project, this would contain actual architectural details. 8 | 9 | ## Technical Architecture (Example) 10 | 11 | ### Backend 12 | 13 | - **API Layer**: Node.js with Express.js 14 | - **Database**: MongoDB for primary data storage 15 | - **Authentication**: JWT-based authentication with OAuth support 16 | - **Caching**: Redis for performance optimization 17 | - **Testing**: Jest for unit and integration testing 18 | 19 | ### Frontend 20 | 21 | - **Web Client**: React.js with TypeScript 22 | - **Mobile Apps**: React Native for iOS and Android 23 | - **State Management**: Redux for predictable state 24 | - **UI Framework**: Material-UI for consistent design 25 | 26 | ## System Components (Example) 27 | 28 | 1. **Authentication Service**: Handles user signup, login, and session management 29 | 2. **Project Management Service**: Manages projects, teams, and permissions 30 | 3. **Task Service**: Core task CRUD operations and business logic 31 | 4. **Notification Service**: Manages user notifications and alerts 32 | 5. **Analytics Service**: Provides usage statistics and reporting 33 | 34 | ## Data Flow (Example) 35 | 36 | 1. Clients authenticate through the Authentication Service 37 | 2. Authenticated requests are routed to the appropriate service 38 | 3. Services interact with the database and return responses 39 | 4. Real-time updates are pushed to clients via WebSockets 40 | 41 | ## Deployment Architecture (Example) 42 | 43 | The system is deployed using containerization with Docker and Kubernetes, providing: 44 | 45 | - Horizontal scalability for handling load spikes 46 | - High availability through multiple replicas 47 | - Zero-downtime deployments 48 | - Environment isolation (development, staging, production) 49 | 50 | ## Security Considerations (Example) 51 | 52 | - All API endpoints are protected with proper authentication 53 | - Sensitive data is encrypted at rest and in transit 54 | - Rate limiting is implemented to prevent abuse 55 | - Regular security audits and penetration testing 56 | -------------------------------------------------------------------------------- /.simone/02_REQUIREMENTS/CLAUDE.md: -------------------------------------------------------------------------------- 1 | # CLAUDE.md - Requirements Folder Structure Guide 2 | 3 | ## Overview 4 | This folder contains all project milestones and their associated requirements documentation. Each milestone represents a major project phase or feature set. 5 | 6 | ## Milestone Naming Convention 7 | **CRITICAL**: Milestone folders MUST follow this exact pattern: 8 | ``` 9 | M##_Milestone_Name/ 10 | ``` 11 | 12 | - `M##` - Two-digit milestone number (M01, M02, etc.) 13 | - `_` - Single underscore separator 14 | - `Milestone_Name` - Descriptive name using underscores for spaces 15 | 16 | ### Examples: 17 | - ✅ `M01_Backend_Setup/` 18 | - ✅ `M02_Frontend_UI/` 19 | - ✅ `M03_Authentication_System/` 20 | - ❌ `M1_Backend/` (missing leading zero) 21 | - ❌ `M01-Backend-Setup/` (wrong separator) 22 | - ❌ `Backend_Setup/` (missing M## prefix) 23 | 24 | ## Milestone Structure 25 | Each milestone folder MUST contain: 26 | 27 | ### 1. Milestone Meta File (REQUIRED) 28 | - **Name**: `M##_milestone_meta.md` 29 | - **Purpose**: Contains milestone metadata and overview 30 | - **Location**: Root of milestone folder 31 | 32 | ### 2. Product Requirements Documents (PRD) 33 | - **Pattern**: `PRD_*.md` 34 | - **Examples**: `PRD_Backend_Setup.md`, `PRD_User_Authentication.md` 35 | - **Purpose**: Define product requirements and user stories 36 | 37 | ### 3. Technical Specifications 38 | - **Pattern**: `SPECS_*.md` 39 | - **Examples**: `SPECS_API_V1.md`, `SPECS_Database_Schema.md` 40 | - **Purpose**: Technical implementation details 41 | 42 | ### 4. Amendments (as needed) 43 | - **Pattern**: `PRD_AMEND_##_*.md` 44 | - **Examples**: `PRD_AMEND_01_Additional_Endpoints.md` 45 | - **Purpose**: Document changes to original requirements 46 | 47 | ## Example Structure 48 | ``` 49 | 02_REQUIREMENTS/ 50 | ├── M01_Backend_Setup/ 51 | │ ├── M01_milestone_meta.md 52 | │ ├── PRD_Backend_Setup.md 53 | │ ├── SPECS_API_V1.md 54 | │ └── PRD_AMEND_01_Cache_Layer.md 55 | ├── M02_Frontend_UI/ 56 | │ ├── M02_milestone_meta.md 57 | │ ├── PRD_User_Interface.md 58 | │ └── SPECS_Component_Library.md 59 | └── M03_Authentication_System/ 60 | ├── M03_milestone_meta.md 61 | ├── PRD_Authentication.md 62 | └── SPECS_OAuth_Integration.md 63 | ``` 64 | 65 | ## Important Notes for Claude Code 66 | 67 | 1. **Always use the M## prefix** when creating milestone folders 68 | 2. **Use underscores** for spaces in milestone names 69 | 3. **Create the milestone meta file first** using the template from `99_TEMPLATES/milestone_meta_template.md` 70 | 4. **Update the project manifest** (`00_PROJECT_MANIFEST.md`) when creating new milestones 71 | 5. **Maintain sequential numbering** - don't skip milestone numbers 72 | 73 | ## Common Mistakes to Avoid 74 | - Creating milestones without the M## prefix 75 | - Using hyphens instead of underscores 76 | - Forgetting the milestone meta file 77 | - Not updating the project manifest 78 | - Creating milestones in the wrong location (must be in 02_REQUIREMENTS) -------------------------------------------------------------------------------- /.simone/02_REQUIREMENTS/M01_Backend_Setup/M01_milestone_meta.md: -------------------------------------------------------------------------------- 1 | --- 2 | milestone_id: M01 3 | title: Backend Setup 4 | status: active # pending | active | completed | blocked | on_hold 5 | last_updated: 2023-07-10 6 | --- 7 | 8 | # Milestone: Backend Setup (EXAMPLE) 9 | 10 | ## Goals 11 | This milestone focuses on establishing the core backend infrastructure for the project, including: 12 | 13 | 1. Setting up the initial project structure 14 | 2. Defining the database schema and models 15 | 3. Implementing basic API endpoints 16 | 4. Establishing authentication and authorization systems 17 | 18 | ## Key Documents 19 | - [Product Requirements Document](./PRD_Backend_Setup.md) 20 | - [API Specifications V1](./SPECS_API_V1.md) 21 | - [Auth Flow Update Amendment](./PRD_AMEND_01_Auth_Flow_Update.md) 22 | 23 | ## Definition of Done (DoD) 24 | This milestone will be considered complete when: 25 | 26 | - The backend server can be started and responds to API requests 27 | - All core models are defined and can be created/updated/deleted via the API 28 | - Authentication is working with JWT tokens 29 | - Basic error handling is implemented 30 | - Integration tests are passing for all endpoints 31 | 32 | ## Notes / Context 33 | This is an example milestone document to demonstrate how milestones might be structured in a project using the Simone framework. The backend infrastructure established here would be the foundation for a typical web application. 34 | 35 | ## Related Sprints 36 | 37 | - [S01_M01_Initial_API](../../03_SPRINTS/S01_M01_Initial_API/S01_sprint_meta.md) 38 | - [S02_M01_Database_Integration](../../03_SPRINTS/S02_M01_Database_Integration/S02_sprint_meta.md) 39 | -------------------------------------------------------------------------------- /.simone/02_REQUIREMENTS/M01_Backend_Setup/PRD_AMEND_01_Auth_Flow_Update.md: -------------------------------------------------------------------------------- 1 | # Amendment: Auth Flow Update (EXAMPLE) 2 | 3 | ## Date: 2023-05-17 4 | 5 | ## Overview 6 | 7 | This amendment updates the authentication flow requirements to incorporate OAuth 2.0 support for social logins in addition to the existing email/password authentication. 8 | 9 | **Note: This is an example amendment document to demonstrate how requirement changes might be tracked in the Simone framework.** 10 | 11 | ## Changes to Product Requirements 12 | 13 | ### User Management (FR-1) 14 | 15 | **Added Requirements:** 16 | 17 | - FR-1.6: The system shall allow users to register and log in using Google OAuth 18 | - FR-1.7: The system shall allow users to register and log in using GitHub OAuth 19 | - FR-1.8: The system shall link social login accounts with existing email accounts when the email matches 20 | 21 | ### Data Models (FR-2) 22 | 23 | **Updated FR-2.1 (User model):** 24 | 25 | Add the following fields to the User model: 26 | - `oauth_provider`: string (null, 'google', 'github') 27 | - `oauth_id`: string (provider-specific user ID) 28 | 29 | ### API Endpoints (FR-3) 30 | 31 | **Added Endpoints to FR-3.1:** 32 | - GET /api/auth/oauth/google (Redirect URL for Google OAuth) 33 | - GET /api/auth/oauth/github (Redirect URL for GitHub OAuth) 34 | - GET /api/auth/oauth/callback (OAuth provider callback) 35 | 36 | ## Changes to Non-Functional Requirements 37 | 38 | **Updated NFR-5:** 39 | - NFR-5: The system shall implement JWT-based authentication with support for OAuth 2.0 providers 40 | 41 | **Added NFR:** 42 | - NFR-9: The system shall securely store OAuth provider credentials in environment variables 43 | 44 | ## Implementation Impact 45 | 46 | - Required libraries: `passport`, `passport-google-oauth20`, `passport-github2` 47 | - Additional environment variables needed: 48 | - `GOOGLE_CLIENT_ID` 49 | - `GOOGLE_CLIENT_SECRET` 50 | - `GITHUB_CLIENT_ID` 51 | - `GITHUB_CLIENT_SECRET` 52 | - `OAUTH_CALLBACK_URL` 53 | 54 | ## Test Cases 55 | 56 | - TC-1: User can log in with Google account 57 | - TC-2: User can log in with GitHub account 58 | - TC-3: Social login with matching email links to existing account 59 | - TC-4: JWT token works correctly regardless of authentication method 60 | 61 | ## Timeline Impact 62 | 63 | Implementation of these changes is expected to add 3 days to the original timeline. 64 | 65 | ## Approvals 66 | 67 | - Requested by: Sarah Chen (Product Manager) 68 | - Approved by: Mike Johnson (Technical Lead) 69 | - Approved by: David Lee (Project Manager) 70 | -------------------------------------------------------------------------------- /.simone/02_REQUIREMENTS/M01_Backend_Setup/PRD_Backend_Setup.md: -------------------------------------------------------------------------------- 1 | # Product Requirements Document: Backend Setup 2 | 3 | ## Overview 4 | 5 | This document outlines the requirements for setting up the backend infrastructure for our application. The backend will provide API endpoints for client applications, handle data persistence, and implement business logic. 6 | 7 | ## Functional Requirements 8 | 9 | ### User Management 10 | 11 | - FR-1.1: The system shall allow users to register with email and password 12 | - FR-1.2: The system shall allow users to log in with their credentials 13 | - FR-1.3: The system shall allow users to reset their password via email 14 | - FR-1.4: The system shall allow users to update their profile information 15 | - FR-1.5: The system shall allow administrators to disable user accounts 16 | 17 | ### Data Models 18 | 19 | - FR-2.1: The system shall implement a User model with fields for: 20 | - Email (unique) 21 | - Password (hashed) 22 | - Profile information (name, avatar, etc.) 23 | - Role (user, admin) 24 | - Account status (active, disabled) 25 | 26 | - FR-2.2: The system shall implement a Project model with fields for: 27 | - Title 28 | - Description 29 | - Creation date 30 | - Owner (User reference) 31 | - Members (User references) 32 | - Status (active, archived) 33 | 34 | - FR-2.3: The system shall implement a Task model with fields for: 35 | - Title 36 | - Description 37 | - Due date 38 | - Assigned user (User reference) 39 | - Project (Project reference) 40 | - Status (todo, in_progress, done) 41 | - Priority (low, medium, high) 42 | 43 | ### API Endpoints 44 | 45 | - FR-3.1: The system shall provide authentication endpoints: 46 | - POST /api/auth/register 47 | - POST /api/auth/login 48 | - POST /api/auth/reset-password 49 | - POST /api/auth/reset-password-confirm 50 | 51 | - FR-3.2: The system shall provide user management endpoints: 52 | - GET /api/users/me 53 | - PUT /api/users/me 54 | - GET /api/users (admin only) 55 | - PUT /api/users/:id (admin only) 56 | 57 | - FR-3.3: The system shall provide project management endpoints: 58 | - GET /api/projects 59 | - POST /api/projects 60 | - GET /api/projects/:id 61 | - PUT /api/projects/:id 62 | - DELETE /api/projects/:id 63 | 64 | - FR-3.4: The system shall provide task management endpoints: 65 | - GET /api/projects/:id/tasks 66 | - POST /api/projects/:id/tasks 67 | - GET /api/tasks/:id 68 | - PUT /api/tasks/:id 69 | - DELETE /api/tasks/:id 70 | 71 | ## Non-Functional Requirements 72 | 73 | - NFR-1: The backend shall be implemented using Node.js and Express 74 | - NFR-2: The system shall use MongoDB for data persistence 75 | - NFR-3: API response time shall be under 200ms for 95% of requests 76 | - NFR-4: The system shall handle up to 1000 concurrent users 77 | - NFR-5: The system shall implement JWT-based authentication 78 | - NFR-6: All API endpoints shall be documented using OpenAPI/Swagger 79 | - NFR-7: The codebase shall have at least 80% test coverage 80 | - NFR-8: The system shall log all errors and API requests 81 | 82 | ## Constraints 83 | 84 | - The backend must be deployable to AWS and Azure 85 | - The system must comply with GDPR requirements for user data 86 | - The API must be versioned to support future changes 87 | 88 | ## Assumptions 89 | 90 | - The client applications will be responsible for input validation 91 | - The backend will be accessed only through the API, not directly 92 | - The database will be hosted on a managed service (MongoDB Atlas) 93 | 94 | ## Dependencies 95 | 96 | - MongoDB Atlas account 97 | - SMTP service for email sending 98 | - JWT secret key management 99 | -------------------------------------------------------------------------------- /.simone/02_REQUIREMENTS/M01_Backend_Setup/SPECS_API_V1.md: -------------------------------------------------------------------------------- 1 | # API Specifications V1 2 | 3 | This document provides detailed specifications for the API endpoints to be implemented in the backend. 4 | 5 | ## Base URL 6 | 7 | All API endpoints are prefixed with: `/api/v1` 8 | 9 | ## Authentication 10 | 11 | All authenticated endpoints require a valid JWT token in the Authorization header: 12 | 13 | ``` 14 | Authorization: Bearer <token> 15 | ``` 16 | 17 | ## Error Handling 18 | 19 | All API endpoints follow a consistent error response format: 20 | 21 | ```json 22 | { 23 | "error": { 24 | "code": "ERROR_CODE", 25 | "message": "Human-readable error message", 26 | "details": {} // Optional additional error details 27 | } 28 | } 29 | ``` 30 | 31 | Common error codes: 32 | - `UNAUTHORIZED`: Authentication required or invalid 33 | - `FORBIDDEN`: Insufficient permissions 34 | - `NOT_FOUND`: Resource not found 35 | - `VALIDATION_ERROR`: Request validation failed 36 | - `INTERNAL_ERROR`: Server-side error 37 | 38 | ## Endpoints 39 | 40 | ### Authentication 41 | 42 | #### POST /api/v1/auth/register 43 | 44 | Register a new user. 45 | 46 | **Request:** 47 | ```json 48 | { 49 | "email": "user@example.com", 50 | "password": "securepassword", 51 | "name": "John Doe" 52 | } 53 | ``` 54 | 55 | **Response (201 Created):** 56 | ```json 57 | { 58 | "user": { 59 | "id": "user123", 60 | "email": "user@example.com", 61 | "name": "John Doe", 62 | "created_at": "2023-07-10T12:00:00Z" 63 | }, 64 | "token": "jwt.token.here" 65 | } 66 | ``` 67 | 68 | #### POST /api/v1/auth/login 69 | 70 | Authenticate a user. 71 | 72 | **Request:** 73 | ```json 74 | { 75 | "email": "user@example.com", 76 | "password": "securepassword" 77 | } 78 | ``` 79 | 80 | **Response (200 OK):** 81 | ```json 82 | { 83 | "user": { 84 | "id": "user123", 85 | "email": "user@example.com", 86 | "name": "John Doe", 87 | "created_at": "2023-07-10T12:00:00Z" 88 | }, 89 | "token": "jwt.token.here" 90 | } 91 | ``` 92 | 93 | ### Users 94 | 95 | #### GET /api/v1/users/me 96 | 97 | Get current authenticated user profile. 98 | 99 | **Response (200 OK):** 100 | ```json 101 | { 102 | "id": "user123", 103 | "email": "user@example.com", 104 | "name": "John Doe", 105 | "created_at": "2023-07-10T12:00:00Z", 106 | "role": "user", 107 | "status": "active" 108 | } 109 | ``` 110 | 111 | #### PUT /api/v1/users/me 112 | 113 | Update current user profile. 114 | 115 | **Request:** 116 | ```json 117 | { 118 | "name": "John Smith", 119 | "avatar_url": "https://example.com/avatar.jpg" 120 | } 121 | ``` 122 | 123 | **Response (200 OK):** 124 | ```json 125 | { 126 | "id": "user123", 127 | "email": "user@example.com", 128 | "name": "John Smith", 129 | "avatar_url": "https://example.com/avatar.jpg", 130 | "created_at": "2023-07-10T12:00:00Z", 131 | "role": "user", 132 | "status": "active" 133 | } 134 | ``` 135 | 136 | ### Projects 137 | 138 | #### GET /api/v1/projects 139 | 140 | List all projects accessible to the authenticated user. 141 | 142 | **Query Parameters:** 143 | - `status` (optional): Filter by status (active, archived) 144 | - `limit` (optional): Maximum number of results (default: 20) 145 | - `offset` (optional): Pagination offset (default: 0) 146 | 147 | **Response (200 OK):** 148 | ```json 149 | { 150 | "total": 42, 151 | "data": [ 152 | { 153 | "id": "proj123", 154 | "title": "Project Alpha", 155 | "description": "This is project alpha", 156 | "created_at": "2023-07-10T12:00:00Z", 157 | "owner": { 158 | "id": "user123", 159 | "name": "John Doe" 160 | }, 161 | "status": "active" 162 | }, 163 | ... 164 | ] 165 | } 166 | ``` 167 | 168 | #### POST /api/v1/projects 169 | 170 | Create a new project. 171 | 172 | **Request:** 173 | ```json 174 | { 175 | "title": "New Project", 176 | "description": "Description of the project" 177 | } 178 | ``` 179 | 180 | **Response (201 Created):** 181 | ```json 182 | { 183 | "id": "proj456", 184 | "title": "New Project", 185 | "description": "Description of the project", 186 | "created_at": "2023-07-15T14:30:00Z", 187 | "owner": { 188 | "id": "user123", 189 | "name": "John Doe" 190 | }, 191 | "status": "active" 192 | } 193 | ``` 194 | 195 | ### Tasks 196 | 197 | #### GET /api/v1/projects/:projectId/tasks 198 | 199 | List tasks for a specific project. 200 | 201 | **Query Parameters:** 202 | - `status` (optional): Filter by status (todo, in_progress, done) 203 | - `assigned_to` (optional): Filter by assigned user ID 204 | - `limit` (optional): Maximum number of results (default: 50) 205 | - `offset` (optional): Pagination offset (default: 0) 206 | 207 | **Response (200 OK):** 208 | ```json 209 | { 210 | "total": 24, 211 | "data": [ 212 | { 213 | "id": "task123", 214 | "title": "Implement login page", 215 | "description": "Create the login page with email and password fields", 216 | "due_date": "2023-08-01T00:00:00Z", 217 | "status": "in_progress", 218 | "priority": "high", 219 | "assigned_to": { 220 | "id": "user123", 221 | "name": "John Doe" 222 | }, 223 | "project_id": "proj123" 224 | }, 225 | ... 226 | ] 227 | } 228 | ``` 229 | 230 | ## Rate Limiting 231 | 232 | API requests are rate-limited to 100 requests per minute per user. When the limit is exceeded, the API will respond with status code 429 (Too Many Requests). 233 | -------------------------------------------------------------------------------- /.simone/03_SPRINTS/CLAUDE.MD: -------------------------------------------------------------------------------- 1 | # Sprint Management Instructions 2 | 3 | ## Important Section - Always read 4 | 5 | - When updating Tasks Logs (Output Log) always fetch current date and time first 6 | - Update Output Log after every Subtask 7 | - Always be truthful in Logs. If you cannot complete a task for technical reasons, just write it down. Don't lie! 8 | - Only mark lines as done if you could acctually progress them. 9 | - Update the task file after every completed subtask and check Acceptance criteria as well if successful. 10 | 11 | ## Sprint Structure 12 | 13 | Sprints are organized by milestone and sequence: 14 | 15 | - Folders follow pattern: `S<NN>_M<NN>_<Focus_Area>/` where: 16 | - `S<NN>` is the sprint sequence number 17 | - `M<NN>` directly references the milestone ID this sprint belongs to 18 | - `<Focus_Area>` describes the sprint's main focus 19 | - Each sprint has a meta file: `S<NN>_sprint_meta.md` 20 | - Tasks use pattern: `T<NN>_S<NN>_<Description>.md` 21 | 22 | ## Sprint Meta Files 23 | 24 | Sprint meta files define sprint goals and track status: 25 | 26 | ```yaml 27 | --- 28 | sprint_id: S01 29 | milestone_id: M01 30 | status: in_progress # planning | in_progress | review | complete 31 | --- 32 | ``` 33 | 34 | Update status as progress occurs: 35 | 36 | - planning → in_progress → review → complete 37 | 38 | Always use the template at `.simone/99_TEMPLATES/sprint_template.md` when creating new sprint meta files. 39 | 40 | ## Sprint Tasks 41 | 42 | Tasks within a sprint follow a standard format: 43 | 44 | - Status progression: open → in_progress → pending_review → done 45 | - When completing a task: 46 | - Ask for user confirmation 47 | - Update status to "done" 48 | - Rename file from T... to TX... (e.g., `TX01_S01_Task_Name.md`) 49 | - Update Output Log with final entry 50 | 51 | Always use the template at `.simone/99_TEMPLATES/task_template.md` when creating new sprint tasks. 52 | 53 | ## Working with Sprint Tasks 54 | 55 | When executing a sprint task: 56 | 57 | 1. Analyze task's Acceptance Criteria and Subtasks 58 | 2. Update status to "in_progress" 59 | 3. Log activities in the Output Log with timestamps after every Subtask(!) 60 | 4. Mark subtasks as completed using [x] only when they are really completed. If you were not able to complete them, don't mark them and tell the user. 61 | 5. Reference architectural guidelines when implementing technical solutions 62 | 6. Ensure the task follows the structure from the task template 63 | -------------------------------------------------------------------------------- /.simone/03_SPRINTS/S01_M01_Initial_API/S01_sprint_meta.md: -------------------------------------------------------------------------------- 1 | --- 2 | sprint_folder_name: S01_M01_Initial_API 3 | sprint_sequence_id: S01 4 | milestone_id: M01 5 | title: Initial API Development 6 | status: active # pending | active | completed | aborted 7 | goal: Implement the foundational API structure including user authentication, basic project endpoints, and the initial database models. 8 | last_updated: 2023-07-15 9 | --- 10 | 11 | # Sprint: Initial API Development (S01) (EXAMPLE) 12 | 13 | ## Sprint Goal 14 | Implement the foundational API structure including user authentication, basic project endpoints, and the initial database models. 15 | 16 | ## Scope & Key Deliverables 17 | 1. Set up the project structure with Express.js and MongoDB 18 | 2. Implement user registration and authentication endpoints 19 | 3. Create basic project and task models 20 | 4. Implement core API endpoints for projects and tasks 21 | 5. Set up automated testing infrastructure 22 | 23 | ## Sprint Backlog 24 | - [T01_S01_Setup_Project_Structure](./T01_S01_Setup_Project_Structure.md) 25 | - [T02_S01_Define_User_Model](./T02_S01_Define_User_Model.md) 26 | - [T03_S01_Implement_Auth_Endpoints](./T03_S01_Implement_Auth_Endpoints.md) 27 | - [T04_S01_Define_Project_Model](./T04_S01_Define_Project_Model.md) 28 | - [T05_S01_Implement_Project_Endpoints](./T05_S01_Implement_Project_Endpoints.md) 29 | 30 | ## Definition of Done (for the Sprint) 31 | The sprint will be considered complete when: 32 | - All sprint tasks are completed and meet their acceptance criteria 33 | - All implemented endpoints pass their test cases 34 | - API documentation is updated to reflect implemented endpoints 35 | - Code has been reviewed and merged to the development branch 36 | 37 | ## Notes / Context 38 | This is an example sprint document to demonstrate how sprints might be structured in a project using the Simone framework. This simulates what a typical initial API development sprint might look like. 39 | 40 | ## Related Documents 41 | - [Milestone M01: Backend Setup](../../02_REQUIREMENTS/M01_Backend_Setup/M01_milestone_meta.md) 42 | - [API Specifications V1](../../02_REQUIREMENTS/M01_Backend_Setup/SPECS_API_V1.md) 43 | -------------------------------------------------------------------------------- /.simone/03_SPRINTS/S01_M01_Initial_API/T01_S01_Setup_Project_Structure.md: -------------------------------------------------------------------------------- 1 | --- 2 | task_id: T01_S01 3 | sprint_sequence_id: S01 4 | status: in_progress # open | in_progress | pending_review | done | failed | blocked 5 | complexity: Medium # Low | Medium | High 6 | last_updated: 2023-07-15 7 | --- 8 | 9 | # Task: Setup Project Structure (EXAMPLE) 10 | 11 | ## Description 12 | Set up the initial project structure for the backend API service, including directory organization, dependency installation, and basic configuration. 13 | 14 | **Note: This is an example task to demonstrate the structure of a task in the Simone framework.** 15 | 16 | ## Goal / Objectives 17 | - Create a well-organized, scalable project structure 18 | - Set up the Express.js application with middleware 19 | - Configure MongoDB connection 20 | - Implement basic error handling 21 | - Set up environment configuration 22 | - Initialize logging system 23 | 24 | ## Acceptance Criteria 25 | - [ ] Project structure follows MVC pattern with clear separation of concerns 26 | - [ ] Express application is set up with necessary middleware (CORS, body-parser, etc.) 27 | - [ ] MongoDB connection is configured with error handling 28 | - [ ] Environment variables are properly managed (development vs production) 29 | - [ ] Logger is implemented for request/error tracking 30 | - [ ] Basic error handling middleware is implemented 31 | - [ ] Project runs without errors 32 | - [ ] Initial tests pass 33 | 34 | ## Subtasks 35 | - [ ] Initialize Node.js project with package.json 36 | - [ ] Install core dependencies (express, mongoose, dotenv, etc.) 37 | - [ ] Create directory structure for routes, controllers, models, middleware 38 | - [ ] Set up Express application with basic middleware 39 | - [ ] Configure MongoDB connection 40 | - [ ] Implement environment-specific configurations 41 | - [ ] Set up logging system 42 | - [ ] Implement error handling middleware 43 | - [ ] Write basic tests to verify configuration 44 | 45 | ## Output Log 46 | 47 | [2023-07-15 14:30:00] Started task 48 | [2023-07-15 14:45:22] Created files: package.json, .env.example 49 | [2023-07-15 15:10:05] Created directory structure and base files: app.js, server.js, config/db.js, config/env.js 50 | [2023-07-15 15:30:18] Created middleware: middleware/auth.js, middleware/error.js 51 | [2023-07-15 15:45:30] Created util files: utils/logger.js 52 | [2023-07-15 16:10:15] Created base routes: routes/index.js 53 | [2023-07-15 16:45:22] Implemented error handling in middleware/error.js 54 | [2023-07-15 17:20:10] Configured logging system in utils/logger.js 55 | [2023-07-15 18:20:45] Added Jest configuration and created sample tests 56 | [2023-07-15 18:35:30] Completed all subtasks, verified server starts successfully 57 | -------------------------------------------------------------------------------- /.simone/04_GENERAL_TASKS/CLAUDE.MD: -------------------------------------------------------------------------------- 1 | # General Tasks Instructions 2 | 3 | ## General Task Structure 4 | 5 | General tasks are standalone work items not tied to sprints: 6 | 7 | - Files follow pattern: `T<NNN>_<Description>.md` 8 | - Completed tasks: `TX<NNN>_<Description>.md` 9 | 10 | Always use the template at `.simone/99_TEMPLATES/task_template.md` when creating new general tasks. 11 | 12 | ## Task Formatting 13 | 14 | General tasks use standardized YAML frontmatter and sections: 15 | 16 | ```yaml 17 | --- 18 | task_id: T001 19 | status: open # open | in_progress | pending_review | done | failed | blocked 20 | complexity: Medium # Low | Medium | High 21 | last_updated: YYYY-MM-DD HH:MM 22 | --- 23 | ``` 24 | 25 | The full task structure with all sections is defined in the task template. Always maintain this structure. 26 | 27 | ## Working with General Tasks 28 | 29 | When handling general tasks: 30 | 31 | 1. Update the status field as you progress 32 | 2. Record timestamps in this format (YYYY-MM-DD HH:MM) 33 | 3. Log all significant actions in the Output Log section: 34 | 35 | ```plaintext 36 | [YYYY-MM-DD HH:MM] Started task 37 | [YYYY-MM-DD HH:MM] Modified files: file1.js, file2.js 38 | ``` 39 | 40 | 4. Mark subtasks as they're completed: `- [x] Completed subtask` 41 | 5. Use the Acceptance Criteria as your primary completion checklist 42 | 6. Ensure all sections from the task template are preserved 43 | 44 | ## Task Completion Process 45 | 46 | When a task is complete: 47 | 48 | 1. Update status to "done" 49 | 2. Update all Acceptance Criteria with [x] 50 | 3. Add final Output Log entry 51 | 4. Rename file from T... to TX... (e.g., `TX001_Task_Name.md`) 52 | -------------------------------------------------------------------------------- /.simone/04_GENERAL_TASKS/T002_API_Rate_Limiting.md: -------------------------------------------------------------------------------- 1 | --- 2 | task_id: T002 3 | status: in_progress # open | in_progress | pending_review | done | failed | blocked 4 | complexity: Medium # Low | Medium | High 5 | last_updated: 2023-07-25T09:15:00Z 6 | --- 7 | 8 | # Task: API Rate Limiting (EXAMPLE) 9 | 10 | ## Description 11 | Implement rate limiting for the API to prevent abuse and ensure fair usage across all clients. This task involves adding middleware to track and limit requests based on client IP or API key. 12 | 13 | **Note: This is an example general task to demonstrate how non-sprint-specific tasks might be structured in the Simone framework.** 14 | 15 | ## Goal / Objectives 16 | - Protect API endpoints from abuse and excessive requests 17 | - Implement configurable rate limits based on client authentication 18 | - Track usage statistics for billing and monitoring 19 | - Provide clear feedback to clients when limits are exceeded 20 | - Ensure minimal performance impact on normal API operation 21 | 22 | ## Acceptance Criteria 23 | - [ ] Rate limiting is applied to all public API endpoints 24 | - [ ] Different rate limits are configurable based on client tier/authentication 25 | - [ ] Response headers include rate limit information (limit, remaining, reset) 26 | - [ ] When limit is exceeded, a 429 status code is returned with appropriate error message 27 | - [ ] Rate limiting can be temporarily disabled for specific clients if needed 28 | - [ ] Implementation has minimal impact on response times (<10ms overhead) 29 | - [ ] Usage statistics are collected for monitoring and analysis 30 | 31 | ## Subtasks 32 | - [x] Research rate limiting strategies and best practices 33 | - [x] Evaluate libraries (express-rate-limit, rate-limiter-flexible, etc.) 34 | - [x] Design rate limit tiers for different client types 35 | - [ ] Implement rate limiting middleware 36 | - [ ] Add custom response headers 37 | - [ ] Create storage adapter for distributed rate limiting 38 | - [ ] Implement override mechanism for special cases 39 | - [ ] Add monitoring and alerts for rate limit events 40 | - [ ] Document rate limiting behavior for API consumers 41 | 42 | ## Output Log 43 | *(This section is populated as work progresses on the task)* 44 | 45 | [2023-07-23 10:30:00] Started task 46 | [2023-07-23 13:45:22] Completed research on rate limiting strategies 47 | [2023-07-24 09:15:30] Evaluated rate-limiter-flexible and express-rate-limit libraries 48 | [2023-07-24 15:50:15] Decided on rate-limiter-flexible for implementation 49 | [2023-07-25 09:15:00] Designed rate limit tiers for different client authentication levels 50 | -------------------------------------------------------------------------------- /.simone/04_GENERAL_TASKS/TX001_Refactor_Logging_Module.md: -------------------------------------------------------------------------------- 1 | --- 2 | task_id: T001 3 | status: done # open | in_progress | pending_review | done | failed | blocked 4 | complexity: Medium # Low | Medium | High 5 | last_updated: 2023-07-22T16:45:00Z 6 | --- 7 | 8 | # Task: Refactor Logging Module (EXAMPLE) 9 | 10 | ## Description 11 | The current logging implementation is basic and needs to be enhanced to provide better visibility and monitoring capabilities. This task involves refactoring the logging module to add structured logging, log rotation, and improved error tracking. 12 | 13 | **Note: This is an example general task to demonstrate how non-sprint-specific tasks might be structured in the Simone framework.** 14 | 15 | ## Goal / Objectives 16 | - Implement structured JSON logging for better parsing by log analysis tools 17 | - Add log rotation to prevent log files from growing too large 18 | - Enable different log levels based on environment 19 | - Add request ID tracking for tracing requests through the system 20 | - Improve error logging with stack traces and contextual information 21 | 22 | ## Acceptance Criteria 23 | - [x] Logs are output in structured JSON format 24 | - [x] Log files are rotated based on size and/or date 25 | - [x] Different log levels are used appropriately (debug, info, warn, error) 26 | - [x] Each request has a unique ID that is logged with every related log entry 27 | - [x] Error logs include stack traces and relevant request information 28 | - [x] Performance impact of logging is minimal 29 | - [x] Documentation is updated to reflect new logging capabilities 30 | 31 | ## Subtasks 32 | - [x] Evaluate and select appropriate logging libraries and tools 33 | - [x] Design the structured log format with required fields 34 | - [x] Implement log rotation configuration 35 | - [x] Add request ID middleware for request tracking 36 | - [x] Enhance error logging with more contextual information 37 | - [x] Update logging throughout the application to use new formats 38 | - [x] Write tests for logging functionality 39 | - [x] Document the new logging system 40 | 41 | ## Output Log 42 | *(This section is populated as work progresses on the task)* 43 | 44 | [2023-07-15 10:30:00] Started task 45 | [2023-07-15 11:15:22] Researched logging libraries: winston, pino, bunyan 46 | [2023-07-15 13:45:30] Created prototype with winston for structured JSON logging 47 | [2023-07-15 15:20:15] Implemented log rotation with winston-daily-rotate-file 48 | [2023-07-15 16:40:05] Added request ID middleware 49 | [2023-07-15 17:30:18] Enhanced error logging with stack traces and context 50 | [2023-07-16 09:15:40] Updated application code to use new logging format 51 | [2023-07-18 14:22:10] Wrote tests for logging functionality 52 | [2023-07-20 11:05:33] Updated documentation with logging guidelines 53 | [2023-07-22 16:45:00] Task completed 54 | -------------------------------------------------------------------------------- /.simone/05_ARCHITECTURAL_DECISIONS/ADR001_Chosen_Database_System.md: -------------------------------------------------------------------------------- 1 | # ADR 001: Chosen Database System (EXAMPLE) 2 | 3 | ## Status 4 | 5 | Accepted 6 | 7 | ## Date 8 | 9 | 2023-07-05 10 | 11 | ## Context 12 | 13 | The backend system needs a database to store user accounts, projects, tasks, and other application data. The choice of database system will impact performance, scalability, development speed, and maintenance requirements. 14 | 15 | **Note: This is an example Architecture Decision Record to demonstrate how ADRs might be structured in the Simone framework.** 16 | 17 | We evaluated several options including: 18 | - Relational databases (PostgreSQL, MySQL) 19 | - Document databases (MongoDB, CouchDB) 20 | - Key-value stores (Redis, DynamoDB) 21 | 22 | ## Decision 23 | 24 | We will use **MongoDB** as the primary database for this project. 25 | 26 | ## Rationale 27 | 28 | The decision was based on the following factors: 29 | 30 | 1. **Schema Flexibility**: The project requirements are expected to evolve rapidly during development. MongoDB's flexible schema allows us to iterate quickly without needing migrations for every model change. 31 | 32 | 2. **JSON-Native Data Model**: Our API communicates in JSON, and MongoDB's BSON format aligns well with our data structures. This reduces the object-relational impedance mismatch. 33 | 34 | 3. **Scalability**: MongoDB's horizontal scaling capabilities via sharding will support our growth projections. 35 | 36 | 4. **Developer Productivity**: The team has prior experience with MongoDB and Mongoose ODM, which will accelerate development. 37 | 38 | 5. **Performance**: For our read-heavy workloads with relatively simple query patterns, MongoDB offers good performance characteristics. 39 | 40 | 6. **Ecosystem**: The robust Node.js ecosystem around MongoDB with libraries like Mongoose provides tools for validation, middleware, and other features that align with our development approach. 41 | 42 | Some concerns were raised about: 43 | - Lack of ACID transactions across multiple documents (though MongoDB does support multi-document transactions now) 44 | - Potential for data duplication in document model 45 | 46 | We determined these concerns were manageable for our use case and outweighed by the benefits. 47 | 48 | ## Alternatives Considered 49 | 50 | ### PostgreSQL 51 | 52 | Pros: 53 | - Mature, proven technology with strong ACID compliance 54 | - Excellent for complex relational data and joins 55 | - Support for JSON data types provides some schema flexibility 56 | 57 | Cons: 58 | - Schema migrations could slow development velocity 59 | - Object-relational mapping adds complexity 60 | - Less natural fit for our document-oriented data model 61 | 62 | ### DynamoDB 63 | 64 | Pros: 65 | - Fully managed service with automatic scaling 66 | - Predictable performance with guaranteed low-latency 67 | - Strong consistency options 68 | 69 | Cons: 70 | - Less flexible query capabilities 71 | - AWS lock-in 72 | - Potentially higher cost for our access patterns 73 | - Less familiar to the development team 74 | 75 | ## Consequences 76 | 77 | ### Positive 78 | 79 | - Faster initial development due to schema flexibility 80 | - Easier object mapping between API and database 81 | - Good performance for our expected read-heavy workloads 82 | - Simplified deployment with MongoDB Atlas 83 | 84 | ### Negative 85 | 86 | - Will require care when modeling relationships between data 87 | - May need supplementary systems (like Redis) for certain use cases 88 | - Need to handle eventual consistency in some parts of the application 89 | 90 | ### Neutral 91 | 92 | - Team will need to follow MongoDB best practices for schema design 93 | - We'll use Mongoose ODM to provide schema validation and middleware 94 | 95 | ## Implementation Notes 96 | 97 | - We will use MongoDB Atlas as the managed service for all environments 98 | - Mongoose will be our ODM of choice 99 | - Initial indexes will be created for user email, project names, and task status 100 | - We will implement soft deletion for most entities 101 | - Data validation will happen at both the Mongoose schema level and API input level 102 | 103 | ## Related Decisions 104 | 105 | - ADR002: API Authentication Method 106 | - ADR004: Caching Strategy (pending) 107 | 108 | ## References 109 | 110 | - [MongoDB Documentation](https://docs.mongodb.com/) 111 | - [Mongoose Documentation](https://mongoosejs.com/docs/) 112 | - MongoDB vs PostgreSQL comparison analysis (internal document) 113 | - Performance benchmark results (internal document) 114 | -------------------------------------------------------------------------------- /.simone/05_ARCHITECTURAL_DECISIONS/ADR002_API_Authentication_Method.md: -------------------------------------------------------------------------------- 1 | # ADR 002: API Authentication Method (EXAMPLE) 2 | 3 | ## Status 4 | 5 | Accepted 6 | 7 | ## Date 8 | 9 | 2023-07-08 10 | 11 | ## Context 12 | 13 | Our API requires a secure authentication mechanism to identify users, protect resources, and control access to endpoints. We needed to select an approach that balances security, usability, and compatibility with our chosen tech stack. 14 | 15 | **Note: This is an example Architecture Decision Record to demonstrate how ADRs might be structured in the Simone framework.** 16 | 17 | Several authentication strategies were considered: 18 | - Session-based authentication with cookies 19 | - JWT (JSON Web Tokens) 20 | - OAuth 2.0 21 | - API keys 22 | - Combinations of the above 23 | 24 | ## Decision 25 | 26 | We will use **JWT (JSON Web Tokens)** as our primary authentication method, with OAuth 2.0 support for social logins. 27 | 28 | ## Rationale 29 | 30 | Our decision was based on the following factors: 31 | 32 | 1. **Statelessness**: JWTs are self-contained and don't require server-side session storage, aligning well with our API-first, potentially distributed architecture. 33 | 34 | 2. **Performance**: Token validation can happen without database lookups for each request, improving API response times. 35 | 36 | 3. **Cross-domain compatibility**: JWTs work well across different domains and in mobile applications, supporting our multi-client strategy. 37 | 38 | 4. **Security feature support**: JWTs support expiration, audience validation, and can be cryptographically signed to ensure integrity. 39 | 40 | 5. **OAuth Integration**: For social logins (Google, GitHub), we can still issue JWTs after OAuth authentication, maintaining a consistent authorization approach. 41 | 42 | 6. **Client-side storage**: JWTs can be securely stored in client-side mechanisms like localStorage or HTTP-only cookies, giving us flexibility in implementation. 43 | 44 | 7. **Industry standard**: JWT is widely adopted, well-documented, and has strong library support in our tech stack. 45 | 46 | We acknowledged some concerns with JWT: 47 | - Token revocation requires additional mechanisms (blacklisting or short expiration with refresh tokens) 48 | - Token size can be larger than simple session IDs 49 | - Token payload is encoded, not encrypted (sensitive data shouldn't be included) 50 | 51 | ## Alternatives Considered 52 | 53 | ### Session-based Authentication 54 | 55 | Pros: 56 | - Well-established, traditional approach 57 | - Easy to implement and understand 58 | - Simple to revoke (delete the session) 59 | 60 | Cons: 61 | - Requires session storage on the server 62 | - Can be problematic in distributed/scaled environments 63 | - Typically relies on cookies which have cross-domain limitations 64 | 65 | ### API Keys 66 | 67 | Pros: 68 | - Very simple to implement 69 | - Good for service-to-service communication 70 | - No expiration management needed 71 | 72 | Cons: 73 | - Not suitable for user authentication 74 | - Limited granularity for permissions 75 | - No built-in standard for claims or payload 76 | 77 | ## Consequences 78 | 79 | ### Positive 80 | 81 | - Simplified server architecture with no session storage requirements 82 | - Improved performance for authentication checks 83 | - Enhanced cross-domain and mobile app support 84 | - Ability to include standard claims (exp, iat, sub, etc.) in the token 85 | 86 | ### Negative 87 | 88 | - Need to implement token refresh mechanism for long-lived sessions 89 | - Need for a token blacklist/revocation strategy 90 | - More complex client-side token management compared to cookies 91 | 92 | ### Neutral 93 | 94 | - Need to carefully design token payload to balance size and information needs 95 | - Will use short-lived access tokens (15 minutes) with longer-lived refresh tokens (7 days) 96 | - Client applications must properly handle token storage and renewal 97 | 98 | ## Implementation Notes 99 | 100 | - We will use the `jsonwebtoken` library for token creation and validation 101 | - Tokens will be signed with RS256 (asymmetric) algorithm 102 | - Access tokens will have a 15-minute expiration 103 | - Refresh tokens will have a 7-day expiration and be single-use 104 | - We will implement a token blacklist using Redis for immediate revocation when needed 105 | - Social login (OAuth) will use Passport.js strategies 106 | - Authentication middleware will validate tokens on protected routes 107 | 108 | ## Related Decisions 109 | 110 | - ADR001: Chosen Database System 111 | - ADR003: API Security Measures (pending) 112 | 113 | ## References 114 | 115 | - [JWT.io](https://jwt.io/) 116 | - [IETF RFC 7519 - JSON Web Token](https://tools.ietf.org/html/rfc7519) 117 | - [Auth0: JWTs vs Sessions](https://auth0.com/blog/cookies-vs-tokens-definitive-guide/) 118 | - [OWASP: JSON Web Token Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html) 119 | -------------------------------------------------------------------------------- /.simone/99_TEMPLATES/adr_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | adr_id: ADR{{number}} 3 | title: "{{title}}" 4 | status: "proposed" # proposed | accepted | deprecated | superseded 5 | date: {{YYYY-MM-DD}} 6 | authors: ["{{author}}"] 7 | --- 8 | 9 | # ADR{{number}}: {{title}} 10 | 11 | ## Status 12 | 13 | {{status}} - {{YYYY-MM-DD}} 14 | 15 | ## Context 16 | 17 | {{What is the issue that we're seeing that is motivating this decision or change?}} 18 | 19 | ## Decision 20 | 21 | {{What is the change that we're proposing or have agreed to implement?}} 22 | 23 | ## Consequences 24 | 25 | ### Positive 26 | 27 | - {{e.g., improvement of quality attribute satisfaction, follows the architectural principles, ...}} 28 | 29 | ### Negative 30 | 31 | - {{e.g., compromising quality attribute, follows the architectural principles, ...}} 32 | 33 | ## Alternatives Considered 34 | 35 | ### {{Alternative 1}} 36 | 37 | {{Description and reasoning for why this was not chosen}} 38 | 39 | ### {{Alternative 2}} 40 | 41 | {{Description and reasoning for why this was not chosen}} 42 | 43 | ## Implementation Notes 44 | 45 | {{Any specific implementation details, migration steps, or technical considerations}} 46 | 47 | ## Related 48 | 49 | - {{Links to related ADRs, issues, or documentation}} -------------------------------------------------------------------------------- /.simone/99_TEMPLATES/milestone_meta_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | milestone_id: M<ID> 3 | title: Milestone Title 4 | status: pending # pending | active | completed | blocked | on_hold 5 | last_updated: YYYY-MM-DD HH:MM 6 | --- 7 | 8 | ## Milestone: {{ title }} 9 | 10 | ### Goals 11 | - Clearly define the primary objectives of this milestone. 12 | - What should be achieved by the end of this milestone? 13 | 14 | ### Key Documents 15 | 16 | List the main requirement documents associated with this milestone (e.g., PRD, Technical Specifications). 17 | 18 | - `PRD_<Milestone_Name>.md` 19 | - `SPECS_<Milestone_Name>.md` 20 | 21 | ### Definition of Done (DoD) 22 | - Specific, measurable criteria that must be met for this milestone to be considered complete. 23 | 24 | ### Notes / Context (Optional) 25 | - Any additional context, high-level strategy, or important notes related to this milestone for Claude. 26 | -------------------------------------------------------------------------------- /.simone/99_TEMPLATES/project_manifest_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | project_name: {{project_name}} 3 | current_milestone_id: {{current_milestone_id}} 4 | highest_sprint_in_milestone: {{highest_sprint_in_milestone}} 5 | current_sprint_id: {{current_sprint_id}} 6 | status: active 7 | last_updated: {{timestamp}} 8 | --- 9 | 10 | # Project Manifest: {{project_name}} 11 | 12 | This manifest serves as the central reference point for the project. It tracks the current focus and links to key documentation. 13 | 14 | ## 1. Project Vision & Overview 15 | 16 | {{project_vision}} 17 | 18 | This project follows a milestone-based development approach. 19 | 20 | ## 2. Current Focus 21 | 22 | - **Milestone:** {{current_milestone_id}} - {{current_milestone_name}} 23 | - **Sprint:** {{current_sprint_id}} - {{current_sprint_name}} 24 | 25 | ## 3. Sprints in Current Milestone 26 | 27 | {{sprint_list}} 28 | 29 | ## 4. Key Documentation 30 | 31 | - [Architecture Documentation](./01_PROJECT_DOCS/ARCHITECTURE.md) 32 | - [Current Milestone Requirements](./02_REQUIREMENTS/{{current_milestone_id}}_{{current_milestone_slug}}/) 33 | - [General Tasks](./04_GENERAL_TASKS/) 34 | 35 | ## 5. Quick Links 36 | 37 | - **Current Sprint:** [{{current_sprint_id}} Sprint Folder](./03_SPRINTS/{{current_sprint_id}}_{{current_milestone_id}}_{{current_sprint_slug}}/) 38 | - **Active Tasks:** Check sprint folder for T##_{{current_sprint_id}}_*.md files 39 | - **Project Reviews:** [Latest Review](./10_STATE_OF_PROJECT/) 40 | -------------------------------------------------------------------------------- /.simone/99_TEMPLATES/sprint_meta_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | sprint_folder_name: S<SprintSequenceID>_M<MilestoneID>_<Short_Name> 3 | sprint_sequence_id: S<ID> 4 | milestone_id: M<ID> 5 | title: Sprint Title - Focus of this Sprint 6 | status: pending # pending | active | completed | aborted 7 | goal: Clearly state the primary objective of this sprint. 8 | last_updated: YYYY-MM-DDTHH:MM:SSZ 9 | --- 10 | 11 | # Sprint: {{ title }} ({{ sprint_sequence_id }}) 12 | 13 | ## Sprint Goal 14 | {{ goal }} 15 | 16 | ## Scope & Key Deliverables (Optional) 17 | - What specific features, fixes, or outcomes are targeted in this sprint for Claude to work on? 18 | 19 | ## Definition of Done (for the Sprint) (Optional) 20 | - What conditions must be met for the sprint itself to be considered successfully completed? 21 | 22 | ## Notes / Retrospective Points (Optional) 23 | - Any specific notes for this sprint. 24 | -------------------------------------------------------------------------------- /.simone/99_TEMPLATES/task_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | task_id: T<TaskNN>_S<SprintSequenceID> # For Sprint Tasks (e.g., T01_S01) OR T<NNN> for General Tasks (e.g., T501) 3 | sprint_sequence_id: S<ID> # e.g., S01 (If part of a sprint, otherwise null or absent) 4 | status: open # open | in_progress | pending_review | done | failed | blocked 5 | complexity: Medium # Low | Medium | High 6 | last_updated: YYYY-MM-DDTHH:MM:SSZ 7 | --- 8 | 9 | # Task: (Filename serves as the descriptive title) 10 | 11 | ## Description 12 | Briefly explain what this task is about. Provide necessary context to understand the 'why' behind the task. 13 | 14 | ## Goal / Objectives 15 | Clearly state what needs to be achieved by completing this task. What does success look like? 16 | - Objective 1 17 | - Objective 2 18 | 19 | ## Acceptance Criteria 20 | Specific, measurable conditions that must be met for this task to be considered 'done'. 21 | - [ ] Criterion 1 is met. 22 | - [ ] Criterion 2 is verified. 23 | 24 | ## Subtasks 25 | A checklist of smaller steps to complete this task. 26 | - [ ] Subtask 1 27 | - [ ] Subtask 2 28 | 29 | ## Output Log 30 | *(This section is populated as work progresses on the task)* 31 | 32 | [YYYY-MM-DD HH:MM:SS] Started task 33 | [YYYY-MM-DD HH:MM:SS] Modified files: file1.js, file2.js 34 | [YYYY-MM-DD HH:MM:SS] Completed subtask: Implemented feature X 35 | [YYYY-MM-DD HH:MM:SS] Task completed 36 | -------------------------------------------------------------------------------- /.simone/CLAUDE.MD: -------------------------------------------------------------------------------- 1 | # CLAUDE.md - Simone Framework Structure Guide 2 | 3 | ## Overview 4 | This is the root directory of the Simone framework structure. It contains all project documentation, requirements, sprints, and organizational files. 5 | 6 | ## Critical Files 7 | 8 | ### Project Manifest 9 | **IMPORTANT**: The project manifest file MUST be named: 10 | ``` 11 | 00_PROJECT_MANIFEST.md 12 | ``` 13 | 14 | **NOT**: 15 | - ❌ `MANIFEST.md` 16 | - ❌ `PROJECT_MANIFEST.md` 17 | - ❌ `project_manifest.md` 18 | 19 | The manifest is the central reference file that tracks: 20 | - Project name and status 21 | - Current milestone and sprint 22 | - Project metadata 23 | - Last updated timestamp 24 | 25 | ## Directory Structure 26 | ``` 27 | .simone/ 28 | ├── 00_PROJECT_MANIFEST.md # Central project reference (CORRECT NAME) 29 | ├── 01_PROJECT_DOCS/ # General project documentation 30 | ├── 02_REQUIREMENTS/ # Milestone-based requirements 31 | ├── 03_SPRINTS/ # Sprint execution folders 32 | ├── 04_GENERAL_TASKS/ # Non-sprint tasks 33 | ├── 05_ARCHITECTURAL_DECISIONS/ # ADR documentation 34 | ├── 10_STATE_OF_PROJECT/ # Project review snapshots 35 | └── 99_TEMPLATES/ # Document templates 36 | ``` 37 | 38 | ## Naming Conventions Summary 39 | 40 | ### Files 41 | - **Project Manifest**: `00_PROJECT_MANIFEST.md` 42 | - **Milestone Meta**: `M##_milestone_meta.md` 43 | - **Sprint Meta**: `S##_M##_sprint_meta.md` 44 | - **Task Files**: `TASK_##_*.md` 45 | - **ADR Files**: `ADR_###_*.md` 46 | 47 | ### Folders 48 | - **Milestones**: `M##_Milestone_Name/` 49 | - **Sprints**: `S##_M##_Sprint_Name/` 50 | - **State Snapshots**: `YYYY-MM-DD_HH-MM_snapshot/` 51 | 52 | ## Important Notes for Claude Code 53 | 54 | 1. **Always create `00_PROJECT_MANIFEST.md`** when initializing a project 55 | 2. **Use the templates** from `99_TEMPLATES/` for consistency 56 | 3. **Follow the naming conventions exactly** - they enable proper sorting and navigation 57 | 4. **Update the manifest** when creating milestones or sprints 58 | 5. **Use underscores** for spaces in folder and file names 59 | 60 | ## Common Initialization Mistakes 61 | - Creating `MANIFEST.md` instead of `00_PROJECT_MANIFEST.md` 62 | - Missing the leading zeros in numbered prefixes 63 | - Using hyphens instead of underscores 64 | - Creating files without using templates 65 | - Not updating the manifest after structural changes -------------------------------------------------------------------------------- /.simone/README.md: -------------------------------------------------------------------------------- 1 | # Simone Framework 2 | 3 | Simone is a project management system designed to work with Claude Code's strengths and limitations. It provides structure for breaking down software projects into manageable, context-aware tasks. 4 | 5 | ## Core Concept 6 | 7 | The fundamental challenge: AI context windows are limited and we can't control what information stays or leaves during long sessions. Simone solves this by starting fresh for each task while providing rich, relevant context. 8 | 9 | ## How Simone Works 10 | 11 | ### 1. Requirements First 12 | 13 | Projects begin with well-documented requirements and specifications: 14 | 15 | **In `01_PROJECT_DOCS/`:** 16 | 17 | - Architecture specifications (ARCHITECTURE.md is required) 18 | - Technical design documents 19 | - API specifications 20 | - Database schemas 21 | - Integration guides 22 | 23 | **In `02_REQUIREMENTS/`:** 24 | 25 | - Product Requirements Documents (PRDs) organized by milestone 26 | - Feature specifications 27 | - User stories and acceptance criteria 28 | 29 | Both directories work together to define what gets built and how. 30 | 31 | ### 2. Structured Breakdown 32 | 33 | Work is organized hierarchically: 34 | 35 | - **Milestones** (M01, M02...) - Major project phases 36 | - **Sprints** (S01, S02...) - Focused work periods within milestones 37 | - **Tasks** (T01, T02...) - Atomic units of work 38 | 39 | ### 3. Task Execution Flow 40 | 41 | Each task follows a strict workflow: 42 | 43 | 1. Task selected from sprint or general tasks 44 | 2. Status updated to `in_progress` 45 | 3. Work performed following acceptance criteria 46 | 4. Automatic code review against requirements 47 | 5. Task marked `done` only after review passes 48 | 6. File renamed with `TX` prefix to indicate completion 49 | 50 | ### 4. Context Management 51 | 52 | For each task, Simone provides: 53 | 54 | - The specific task description and criteria 55 | - Relevant sprint and milestone context 56 | - Architecture and requirements documentation 57 | - Project manifest for current state awareness 58 | 59 | This ensures Claude has exactly what's needed without information overload. 60 | 61 | ### 5. Quality Control 62 | 63 | Built-in review processes maintain standards: 64 | 65 | - **Code Review**: Every task completion triggers requirement validation 66 | - **Project Review**: Regular health checks create timestamped snapshots 67 | - **Zero Tolerance**: Any deviation from specifications fails review 68 | 69 | ## Directory Purpose 70 | 71 | - `00_PROJECT_MANIFEST.md` - Current project state and focus 72 | - `01_PROJECT_DOCS/` - Technical foundation (architecture, APIs, schemas) 73 | - `02_REQUIREMENTS/` - Business requirements organized by milestone 74 | - `03_SPRINTS/` - Sprint organization and task definitions 75 | - `04_GENERAL_TASKS/` - Non-sprint specific tasks 76 | - `05_ARCHITECTURE_DECISIONS/` - ADRs for key decisions 77 | - `10_STATE_OF_PROJECT/` - Project review history 78 | - `99_TEMPLATES/` - Standardized file templates 79 | 80 | ## Commands Overview 81 | 82 | Simone commands (`/project:simone:command`) automate the workflow: 83 | 84 | - Planning: `plan_milestone`, `create_sprint` 85 | - Execution: `create_task`, `do_task`, `code_review` 86 | - Maintenance: `commit`, `project_review`, `discuss_review` 87 | - Utilities: `initialize` 88 | 89 | ## Key Principles 90 | 91 | 1. **Fresh Context**: Each task starts with a clean slate 92 | 2. **Focused Scope**: Tasks are sized for single-session completion 93 | 3. **Rich Context**: Surrounding documentation guides development 94 | 4. **Strict Validation**: Requirements are enforced, not suggested 95 | 5. **Progressive Documentation**: Knowledge accumulates in structured form 96 | 97 | The result: Claude can always work confidently with full project awareness, regardless of session history. 98 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## 2025-05-30 4 | 5 | ### Added 6 | 7 | - `npx hello-simone` quick start command for easy Simone installation 8 | - Interactive, adaptive initialize command that: 9 | - Auto-detects project type and framework 10 | - Guides users through conversational setup 11 | - Creates documentation through Q&A process 12 | - Adapts to existing vs new projects 13 | 14 | ### Changed 15 | 16 | - initialize command completely rewritten for better user experience 17 | - Removed complex branching logic in favor of adaptive process 18 | - Focus on conversational interaction rather than rigid steps 19 | 20 | ### Improved 21 | 22 | - Better handling of existing documentation during setup 23 | - Smart project detection (Node.js, Python, PHP, etc.) 24 | - Milestone creation now interactive and context-aware 25 | 26 | ## 2025-05-29 27 | 28 | ### Added 29 | 30 | - ADR template for architecture decision records 31 | - Task ID filtering in commit command (T01_S02, TX003 patterns) 32 | - YOLO mode in commit command to skip user approval 33 | - Code review results now write to task Output Log sections 34 | - create_general_task command for structured task creation 35 | - create_sprint_tasks command for detailed sprint planning 36 | - create_sprints_from_milestone command for milestone-based sprint planning 37 | - prime command for quick project context loading 38 | - yolo command for autonomous task execution without user interaction 39 | 40 | ### Changed 41 | 42 | - Date format simplified to YYYY-MM-DD HH:MM in templates 43 | - Milestone template heading structure updated 44 | - do_task command now uses parallel subagents and updates project manifest 45 | - project_review command removes timeline pressure and focuses on current state 46 | 47 | ### Removed 48 | 49 | - create_sprint, create_task, plan_milestone commands (replaced by new workflow) 50 | 51 | ## Developer Notes 52 | 53 | This update represents a significant evolution based on real-world usage and user feedback. The command architecture has been substantially enhanced with better use of parallel agents, loops, and conditionals, which work surprisingly well in practice. 54 | 55 | **Command Complexity**: The enhanced commands may behave differently between Claude Opus and Sonnet models. While the complexity might be challenging for Sonnet, testing suggests it should handle the workflows effectively. 56 | 57 | **Task Quality Improvements**: The new `create_sprint_tasks` and `create_general_task` commands now provide much better context and codebase references, resulting in notably higher quality task generation with specific implementation guidance. 58 | 59 | **YOLO Mode Warning**: The standalone `yolo` command requires extreme caution. It should only be used: 60 | 61 | - Within isolated development environments 62 | - With Claude Code's permission-skipping mode enabled (`claude --dangerously-skip-permissions`) 63 | - Never on production systems or systems with important data 64 | 65 | The YOLO mode can potentially modify or delete files outside your project directory. Use at your own risk and only in completely isolated environments. 66 | 67 | **Feedback Welcome**: Submit issues or pull requests on GitHub. This framework continues to evolve based on real-world usage patterns. 68 | 69 | ## 2025-05-23 70 | 71 | Initial release of Simone framework 72 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 Helmi 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Simone for Claude Code 2 | 3 | ## What is this? 4 | 5 | Simone is a directory-based project management system I built to work better with Claude Code. It's basically a set of folders, markdown files, and custom commands that help break down software projects into manageable chunks that AI can handle effectively. 6 | 7 | **⚠️ Complexity Warning**: Simone is a sophisticated system that requires time to understand properly. It's not a simple plug-and-play solution, but rather a framework that works best when you take the time to learn how it operates and adapt it to your workflow. 8 | 9 | **📋 Latest Updates**: See [CHANGELOG.md](CHANGELOG.md) for recent changes and improvements. 10 | 11 | ## How to Get Started 12 | 13 | ### 1. Install Simone 14 | 15 | ```bash 16 | npx hello-simone 17 | ``` 18 | 19 | This sets up the folder structure and installs/updates the command files in your project. Can also be used to update an existing installation - command files get backed up automatically. 20 | 21 | ### 2. Initialize Your Project 22 | 23 | Open your project in Claude Code and run: 24 | 25 | ``` 26 | /project:simone:initialize 27 | ``` 28 | 29 | This guides you through the basic setup process. Works with new or existing codebases, and can help you create project documentation (PRDs, architecture docs) or work with documents you already have. 30 | 31 | ### 3. Set Up Your First Milestone 32 | 33 | Create a milestone folder in `.simone/02_REQUIREMENTS/` named `M01_Your_Milestone_Name` (e.g., `M01_Basic_Application`). Include at least: 34 | 35 | - `M01_PRD.md` - Product requirements document 36 | - Other specs as needed: `M01_Database_Schema.md`, `M01_API_Specs.md`, etc. 37 | 38 | *Note: There's no command for this yet. Use the existing chat from step 2 to guide Claude through milestone creation, ensuring proper naming with the `M##_` prefix and underscores.* 39 | 40 | ### 4. Break Down into Sprints 41 | 42 | ``` 43 | /project:simone:create_sprints_from_milestone 44 | ``` 45 | 46 | This analyzes your milestone and breaks it down into logical sprints. It looks at the entire scope and creates meaningful sprint boundaries without detailed tasks yet. 47 | 48 | ### 5. Create Your First Tasks 49 | 50 | ``` 51 | /project:simone:create_sprint_tasks 52 | ``` 53 | 54 | This analyzes your sprints, reviews documentation, researches necessary information, and identifies knowledge gaps to gain comprehensive understanding of your project. Creates detailed, actionable tasks for the current sprint. 55 | 56 | *Important: Only create tasks for your next sprint, not all sprints upfront. After completing Sprint 1, then create tasks for Sprint 2. This ensures the system can reference your existing codebase and incorporate completed work into future task creation.* 57 | 58 | ### 6. Start Working 59 | 60 | ``` 61 | /project:simone:do_task 62 | ``` 63 | 64 | This will automatically pick a task from your general tasks or sprints. For faster execution, specify a task ID: 65 | 66 | ``` 67 | /project:simone:do_task T01_S01 68 | ``` 69 | 70 | Claude will then work through the specified task with full project context. 71 | 72 | That's the basic workflow to get started! You can also: 73 | 74 | - Create general tasks with `/project:simone:create_general_task` 75 | - Use YOLO mode to run a full sprint autonomously 76 | - Explore other commands in `.claude/commands/simone/` 77 | 78 | **Important**: Simone is a complex system, not a simple set-and-forget tool. It works best when you understand how it operates. Take time to read through the commands and consider adapting them to your workflow. 79 | 80 | ## How it Works 81 | 82 | Simone organizes your project into: 83 | 84 | - **Milestones**: Major features or project phases 85 | - **Sprints**: Groups of related tasks within a milestone 86 | - **Tasks**: Individual work items scoped for one Claude session 87 | 88 | Each task gets full project context so Claude knows exactly what to build and how it fits into your architecture. 89 | 90 | ## Why I built this 91 | 92 | AI coding tools have become incredibly powerful, but they all face the same fundamental challenge: context management. The context window is limited in size, and we have little control over what stays in context and what doesn't. 93 | 94 | The problem with long-running sessions is context decay - as you work, critical project knowledge silently falls off the end of the context window. You don't know what's been forgotten until something goes wrong. 95 | 96 | My solution: Start fresh for each task, but provide rich surrounding context. By keeping tasks focused and well-scoped, I can dedicate more of the context window to relevant project knowledge, requirements, and architectural decisions. This way: 97 | 98 | - Each task starts with exactly the project context it needs 99 | - No critical knowledge gets lost in long sessions 100 | - Claude can work confidently with full awareness of requirements 101 | - The surrounding context guides development, not just the task description 102 | 103 | The result is a task-based workflow where Claude always has the right context for the job at hand. 104 | 105 | ## Key Components 106 | 107 | ### 00_PROJECT_MANIFEST.md 108 | 109 | The central document containing the project's vision, goals, and high-level overview. It serves as the starting point for Claude to understand the project. **Important**: The manifest file must be named exactly `00_PROJECT_MANIFEST.md`, not `MANIFEST.md`. 110 | 111 | ### 01_PROJECT_DOCS/ 112 | 113 | Contains general project documentation including technical specifications, user guides, and API documentation that Claude can reference. 114 | 115 | ### 02_REQUIREMENTS/ 116 | 117 | Organized by milestones, this directory stores product requirements documents (PRDs) and their amendments, providing a clear view of what needs to be built. This helps Claude understand the project requirements. Milestone folders must follow the naming convention `M##_Milestone_Name/` (e.g., `M01_Backend_Setup/`). 118 | 119 | ### 03_SPRINTS/ 120 | 121 | Contains sprint plans and task definitions organized by milestone and sprint sequence. Each sprint folder contains individual task files with detailed information for Claude to work on. 122 | 123 | ### 04_GENERAL_TASKS/ 124 | 125 | Stores task definitions for work not tied to a specific sprint. Completed tasks use a `TX` prefix (e.g., `TX001_Completed_Task.md`), making it easy for Claude to identify what's been done. 126 | 127 | ### 05_ARCHITECTURAL_DECISIONS/ 128 | 129 | Captures significant architectural decisions as Architecture Decision Records (ADRs), documenting the context, options considered, and rationale. This provides critical context for Claude when making technical decisions. Uses a structured ADR template for consistency. 130 | 131 | ### 10_STATE_OF_PROJECT/ 132 | 133 | Contains timestamped project review snapshots created by the `project_review` command. These provide a historical record of project health, technical decisions, and progress over time. 134 | 135 | ### 99_TEMPLATES/ 136 | 137 | Contains standardized templates for different document types to ensure consistency for both humans and Claude: 138 | 139 | - Task templates with structured objectives and acceptance criteria 140 | - Sprint and milestone metadata templates 141 | - ADR template for documenting architectural decisions 142 | - All templates use simplified date formats (YYYY-MM-DD HH:MM) 143 | 144 | ### .claude/commands/simone/ 145 | 146 | Custom Claude Code commands that power the Simone workflow: 147 | 148 | - `initialize` - Set up project structure and documentation 149 | - `create_sprints_from_milestone` - Break milestones into logical sprints 150 | - `create_sprint_tasks` - Generate detailed tasks from sprint plans 151 | - `do_task` - Execute individual tasks with full context 152 | - `yolo` - Autonomous sprint execution (use with caution) 153 | - And many more for testing, reviewing, and project management 154 | 155 | ## Directory Structure 156 | 157 | ```plaintext 158 | .simone/ 159 | ├── 00_PROJECT_MANIFEST.md 160 | ├── 01_PROJECT_DOCS/ 161 | ├── 02_REQUIREMENTS/ 162 | │ ├── M01_Backend_Setup/ 163 | │ ├── M02_Frontend_Setup/ 164 | │ └── ... 165 | ├── 03_SPRINTS/ 166 | │ ├── S01_M01_Initial_API/ 167 | │ ├── S02_M01_Database_Schema/ 168 | │ └── ... 169 | ├── 04_GENERAL_TASKS/ 170 | │ ├── TX001_Refactor_Logging_Module.md # Completed task 171 | │ ├── T002_API_Rate_Limiting.md # Open task 172 | │ └── ... 173 | ├── 05_ARCHITECTURE_DECISIONS/ 174 | │ ├── ADR001_Database_Selection.md 175 | │ └── ... 176 | ├── 10_STATE_OF_PROJECT/ # Project review snapshots 177 | └── 99_TEMPLATES/ 178 | ├── task_template.md 179 | ├── sprint_meta_template.md 180 | └── milestone_meta_template.md 181 | ``` 182 | 183 | ## Configuration Tips 184 | 185 | ### Enabling Parallel Task Execution 186 | 187 | While Simone commands like `create_sprint_tasks` support the `useParallelSubagents` instruction, Claude Code needs to be configured to actually execute tasks in parallel. By default, it only runs one task at a time. 188 | 189 | To enable parallel execution: 190 | 191 | ```bash 192 | # Set the number of parallel tasks (example: 3) 193 | claude config set --global "parallelTasksCount" 3 194 | 195 | # Check your current configuration 196 | claude config list -g 197 | ``` 198 | 199 | **Important considerations:** 200 | 201 | - Choose the number based on your system's capabilities and rate limits 202 | - Parallel execution increases API usage significantly 203 | - Some tasks may have conflicts when run in parallel 204 | - Start with a small number (2-3) and adjust based on your experience 205 | 206 | ## Contributing & Feedback 207 | 208 | I'd love to hear from you! This is very much shaped by how I work, and I'm sure there are tons of improvements to be made. 209 | 210 | - **GitHub Issues**: Best place for bugs and feature requests 211 | - **Anthropic Discord**: Find me @helmi if you want to chat about it 212 | - **Pull Requests**: Very welcome! Let's make this better together 213 | 214 | I'm particularly interested in: 215 | 216 | - How you're using it differently 217 | - What's missing for your workflow 218 | - Ideas for better Claude Code integration 219 | - Different organizational approaches 220 | -------------------------------------------------------------------------------- /SYNC_GUIDE.md: -------------------------------------------------------------------------------- 1 | # Simone Framework Sync Guide 2 | 3 | ## Overview 4 | 5 | This guide explains how to sync Simone framework updates from development projects (like Synapsa) back to the canonical `claude-simone` repository. 6 | 7 | **Important**: This is a ONE-WAY sync process. Framework improvements flow from active development projects → claude-simone, not the other way around. 8 | 9 | ## Current Development Context 10 | 11 | - **Primary Development**: Happens in Synapsa project 12 | - **Framework Evolution**: New commands, templates, and improvements are tested in real use 13 | - **Sync Direction**: Synapsa → claude-simone (when improvements are stable) 14 | - **Manual Review**: Each sync should be carefully reviewed, not automated 15 | 16 | ## What to Consider When Syncing 17 | 18 | Before syncing, ask yourself: 19 | 1. Is this change Synapsa-specific or would it benefit all Simone users? 20 | 2. Has this been tested enough in real use? 21 | 3. Will this break existing workflows? 22 | 4. Is the change documented clearly? 23 | 24 | ## What Gets Synced 25 | 26 | ### Framework Core (Always Sync) 27 | ``` 28 | /.claude/commands/simone/ # All command definitions 29 | /.simone/99_TEMPLATES/ # All templates 30 | /.simone/CLAUDE.MD # Framework instructions 31 | /.simone/README.md # Framework documentation 32 | ``` 33 | 34 | ### Framework Structure (Sync Structure Only) 35 | ``` 36 | /.simone/10_STATE_OF_PROJECT/ # Directory only, not contents 37 | ``` 38 | 39 | ### Project-Specific (Never Sync) 40 | ``` 41 | /.simone/00_PROJECT_MANIFEST.md 42 | /.simone/01_PROJECT_DOCS/* 43 | /.simone/02_REQUIREMENTS/* 44 | /.simone/03_SPRINTS/* 45 | /.simone/04_GENERAL_TASKS/* 46 | /.simone/05_ARCHITECTURAL_DECISIONS/* 47 | /.simone/10_STATE_OF_PROJECT/* (contents) 48 | ``` 49 | 50 | ## Manual Sync Process (Synapsa → claude-simone) 51 | 52 | 1. **Identify What Changed** 53 | ```bash 54 | # From claude-simone directory 55 | # Compare commands 56 | diff -r ./.claude/commands/simone/ ~/code/synapsa/.claude/commands/simone/ 57 | 58 | # Compare templates 59 | diff -r ./.simone/99_TEMPLATES/ ~/code/synapsa/.simone/99_TEMPLATES/ 60 | 61 | # Check for new structural elements 62 | ls -la ~/code/synapsa/.simone/ 63 | ``` 64 | 65 | 2. **Review Each Change Carefully** 66 | - Read through command changes - are they improvements or project-specific? 67 | - Check template modifications - are they more generic or more specific? 68 | - Look for new directories or conventions 69 | 70 | 3. **Selective Manual Copy** 71 | - Copy only framework improvements 72 | - Leave out Synapsa-specific adaptations 73 | - Preserve generic examples in claude-simone 74 | 75 | 4. **Test in claude-simone Context** 76 | - Ensure examples still make sense 77 | - Verify commands work with generic project structure 78 | - Check that documentation is project-agnostic 79 | 80 | 5. **Document Changes for Users** 81 | - Update README.md with new features or changes 82 | - Add usage examples for new commands 83 | - Note any breaking changes or migration needs 84 | - Consider creating a CHANGELOG.md for version history 85 | 86 | 6. **Prepare for GitHub Push** 87 | - Review all documentation for clarity 88 | - Ensure examples are helpful and generic 89 | - Check that getting started instructions still work 90 | - Commit with clear message about what's new 91 | 92 | ## Sync Decision Tree 93 | 94 | ``` 95 | Is it a command file? → YES → Sync it 96 | ↓ NO 97 | Is it a template? → YES → Sync it 98 | ↓ NO 99 | Is it CLAUDE.MD or README.md in .simone/? → YES → Sync it 100 | ↓ NO 101 | Is it a new directory structure? → YES → Create directory only 102 | ↓ NO 103 | Don't sync (project-specific content) 104 | ``` 105 | 106 | ## Handling Conflicts 107 | 108 | ### Command Updates 109 | - New commands: Add directly 110 | - Modified commands: Review changes, ensure compatibility 111 | - Removed commands: Keep if still used in project 112 | 113 | ### Template Changes 114 | - Always take latest version from claude-simone 115 | - Templates should be generic enough for all projects 116 | 117 | ### Structure Changes 118 | - New directories: Add to all projects 119 | - Directory renames: Carefully migrate with content preservation 120 | 121 | ## Best Practices 122 | 123 | 1. **Regular Syncs**: Sync framework updates monthly or when new features are announced 124 | 2. **Test After Sync**: Run a few commands to ensure everything works 125 | 3. **Document Custom Changes**: If you modify framework files, document why 126 | 4. **Contribute Back**: If you improve templates or commands, PR to claude-simone 127 | 128 | ## Example: Syncing to Synapsa 129 | 130 | ```bash 131 | # From synapsa directory 132 | cd ~/code/synapsa 133 | 134 | # Dry run first 135 | rsync -av --dry-run \ 136 | --include='/.claude/commands/simone/***' \ 137 | --include='/.simone/99_TEMPLATES/***' \ 138 | --include='/.simone/CLAUDE.MD' \ 139 | --include='/.simone/README.md' \ 140 | --exclude='/*' \ 141 | ~/code/claude-simone/ ./ 142 | 143 | # If looks good, run without --dry-run 144 | rsync -av \ 145 | --include='/.claude/commands/simone/***' \ 146 | --include='/.simone/99_TEMPLATES/***' \ 147 | --include='/.simone/CLAUDE.MD' \ 148 | --include='/.simone/README.md' \ 149 | --exclude='/*' \ 150 | ~/code/claude-simone/ ./ 151 | 152 | # Create any new directories 153 | mkdir -p .simone/10_STATE_OF_PROJECT 154 | ``` 155 | 156 | ## Troubleshooting 157 | 158 | ### Missing Directories 159 | Create them manually: `mkdir -p .simone/10_STATE_OF_PROJECT` 160 | 161 | ### Command Not Working 162 | Check if it depends on new directory structures or conventions 163 | 164 | ### Merge Conflicts 165 | Always prefer claude-simone version for framework files 166 | 167 | ## Future Improvements 168 | 169 | - [ ] Automated sync script with safety checks 170 | - [ ] Version tracking for framework components 171 | - [ ] Compatibility matrix for different Simone versions 172 | - [ ] Migration guides for breaking changes -------------------------------------------------------------------------------- /sync-simone.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Simone Framework Sync Script 3 | # 4 | # NOTE: This script is kept for reference but should be used with extreme caution. 5 | # The primary sync flow is: Active Development (Synapsa) → claude-simone 6 | # Not the other way around. Manual review is strongly recommended over automated sync. 7 | # 8 | # Original purpose: Syncs framework components from claude-simone to a project 9 | # Current reality: Development happens in Synapsa, syncs back to claude-simone 10 | 11 | set -e 12 | 13 | # Colors for output 14 | RED='\033[0;31m' 15 | GREEN='\033[0;32m' 16 | YELLOW='\033[1;33m' 17 | NC='\033[0m' # No Color 18 | 19 | # Default source path (can be overridden) 20 | SOURCE_PATH="${SIMONE_SOURCE:-$HOME/code/claude-simone}" 21 | TARGET_PATH="." 22 | 23 | # Usage 24 | usage() { 25 | echo "Usage: $0 [options]" 26 | echo "Options:" 27 | echo " -s, --source PATH Source claude-simone path (default: $SOURCE_PATH)" 28 | echo " -t, --target PATH Target project path (default: current directory)" 29 | echo " -d, --dry-run Show what would be synced without doing it" 30 | echo " -h, --help Show this help message" 31 | exit 1 32 | } 33 | 34 | # Parse arguments 35 | DRY_RUN="" 36 | while [[ $# -gt 0 ]]; do 37 | case $1 in 38 | -s|--source) 39 | SOURCE_PATH="$2" 40 | shift 2 41 | ;; 42 | -t|--target) 43 | TARGET_PATH="$2" 44 | shift 2 45 | ;; 46 | -d|--dry-run) 47 | DRY_RUN="--dry-run" 48 | shift 49 | ;; 50 | -h|--help) 51 | usage 52 | ;; 53 | *) 54 | echo "Unknown option: $1" 55 | usage 56 | ;; 57 | esac 58 | done 59 | 60 | # Verify source exists 61 | if [ ! -d "$SOURCE_PATH/.simone" ]; then 62 | echo -e "${RED}Error: Source path doesn't appear to be a claude-simone repository${NC}" 63 | echo "Path: $SOURCE_PATH" 64 | exit 1 65 | fi 66 | 67 | # Verify target exists 68 | if [ ! -d "$TARGET_PATH/.simone" ]; then 69 | echo -e "${RED}Error: Target path doesn't appear to have Simone installed${NC}" 70 | echo "Path: $TARGET_PATH" 71 | exit 1 72 | fi 73 | 74 | # Show what we're doing 75 | echo -e "${GREEN}Simone Framework Sync${NC}" 76 | echo "Source: $SOURCE_PATH" 77 | echo "Target: $TARGET_PATH" 78 | if [ -n "$DRY_RUN" ]; then 79 | echo -e "${YELLOW}DRY RUN MODE - No changes will be made${NC}" 80 | fi 81 | echo "" 82 | 83 | # Function to sync a component 84 | sync_component() { 85 | local component=$1 86 | local description=$2 87 | 88 | echo -e "${GREEN}Syncing $description...${NC}" 89 | 90 | # Build rsync command 91 | if [[ "$component" == *"***" ]]; then 92 | # It's a directory with contents 93 | rsync -av $DRY_RUN \ 94 | --include="$component" \ 95 | --exclude='/*' \ 96 | "$SOURCE_PATH/" "$TARGET_PATH/" 97 | else 98 | # It's a single file 99 | rsync -av $DRY_RUN \ 100 | "$SOURCE_PATH/$component" "$TARGET_PATH/$component" 101 | fi 102 | } 103 | 104 | # Sync commands 105 | sync_component "/.claude/commands/simone/***" "Claude commands" 106 | 107 | # Sync templates 108 | sync_component "/.simone/99_TEMPLATES/***" "Project templates" 109 | 110 | # Sync framework docs 111 | echo -e "${GREEN}Syncing framework documentation...${NC}" 112 | rsync -av $DRY_RUN \ 113 | "$SOURCE_PATH/.simone/CLAUDE.MD" \ 114 | "$SOURCE_PATH/.simone/README.md" \ 115 | "$TARGET_PATH/.simone/" 116 | 117 | # Create new directories if needed 118 | echo -e "${GREEN}Ensuring directory structure...${NC}" 119 | if [ -z "$DRY_RUN" ]; then 120 | mkdir -p "$TARGET_PATH/.simone/10_STATE_OF_PROJECT" 121 | echo "Created: .simone/10_STATE_OF_PROJECT/" 122 | else 123 | echo "Would create: .simone/10_STATE_OF_PROJECT/" 124 | fi 125 | 126 | # Summary 127 | echo "" 128 | echo -e "${GREEN}Sync complete!${NC}" 129 | if [ -n "$DRY_RUN" ]; then 130 | echo -e "${YELLOW}This was a dry run. Run without -d to apply changes.${NC}" 131 | else 132 | echo "Framework components have been updated." 133 | echo "" 134 | echo "Next steps:" 135 | echo "1. Test a few commands to ensure everything works" 136 | echo "2. Review SYNC_GUIDE.md for any manual steps" 137 | echo "3. Commit the framework updates" 138 | fi --------------------------------------------------------------------------------