From b03160437e98f78badbb7a44ddb5d717b917823d Mon Sep 17 00:00:00 2001 From: Bernd Worsch Date: Mon, 22 Sep 2025 01:28:55 +0200 Subject: [PATCH] build: Add issue workspace system for structured TDD workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add start-issue NUM=X target to create structured issue workspaces - Add add-test target for iterative test generation within workspace - Add workspace-status target to monitor active workspace state - Add finish-issue target to move tests to main and cleanup workspace - Create workspace structure with requirements.md and test_plan.md templates - Include .markitect_workspace/ in .gitignore for temporary development files - Enable multiple test generation per issue with proper organization - Provide guided workflow for issue breakdown and test planning This replaces single test generation with comprehensive workspace approach supporting complex issues requiring multiple test scenarios. ๐Ÿค– Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .gitignore | 3 + Makefile | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 160 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 77fcc507..c0c6229e 100644 --- a/.gitignore +++ b/.gitignore @@ -71,3 +71,6 @@ __pypackages__/ .DS_Store Thumbs.db +# MarkiTect issue workspace (temporary development files) +.markitect_workspace/ + diff --git a/Makefile b/Makefile index 1f35603d..a13c83da 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ # MarkiTect - Advanced Markdown Engine # Makefile for common development tasks -.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest add-diary-entry list-issues show-issue list-open-issues test-from-issue +.PHONY: help setup install test build clean update status dev lint format check-deps venv-status update-digest add-diary-entry list-issues show-issue list-open-issues test-from-issue start-issue add-test finish-issue workspace-status # Default target help: @@ -40,6 +40,12 @@ help: @echo "" @echo "Test-Driven Development:" @echo " test-from-issue NUM=X - Generate test skeleton from issue (requires Claude Code)" + @echo "" + @echo "Issue Workspace:" + @echo " start-issue NUM=X - Start working on issue (creates workspace)" + @echo " add-test - Add test to current issue workspace" + @echo " workspace-status - Show current workspace state" + @echo " finish-issue - Complete issue work (moves tests to main)" # Python and virtual environment setup PYTHON := python3 @@ -218,6 +224,10 @@ REPO_OWNER := coulomb REPO_NAME := markitect_project ISSUES_API := $(GITEA_URL)/api/v1/repos/$(REPO_OWNER)/$(REPO_NAME)/issues +# Issue workspace configuration +WORKSPACE_DIR := .markitect_workspace +CURRENT_ISSUE_FILE := $(WORKSPACE_DIR)/current_issue.json + # List all gitea issues list-issues: @echo "๐Ÿ“‹ MarkiTect Issues from Gitea Repository" @@ -299,3 +309,149 @@ test-from-issue: @echo "โœ… curl found" @echo "๐Ÿ“‹ Fetching issue #$(NUM) details..." @curl -s "$(ISSUES_API)/$(NUM)" | jq -r 'if .title then "โœ… Issue #$(NUM): " + .title + "\n\n๐Ÿงช Generating test skeleton...\n Please ask Claude Code to generate a test for this issue:\n\n Command: '"'"'Generate a test skeleton for issue #$(NUM)'"'"'\n\n๐Ÿ“‹ Issue Details:\n Title: " + .title + "\n Description: " + .body + "\n\n๐Ÿ“ Test Requirements:\n - Follow TDD principles (test first, then implementation)\n - Use pytest framework (existing project convention)\n - Place test in tests/ directory\n - Name test file: test_issue_$(NUM)_*.py\n - Include docstring referencing issue #$(NUM)\n - Test should initially fail (red state)\n\n๐Ÿ’ก After generation, run '"'"'make test'"'"' to verify test fails initially" else "โŒ Issue #$(NUM) not found or API error\n Use '"'"'make list-open-issues'"'"' to see available issues" end' 2>/dev/null || echo "โŒ Issue #$(NUM) not found or API error" + +# Start working on an issue (creates workspace) +start-issue: + @if [ -z "$(NUM)" ]; then \ + echo "โŒ Please specify issue number: make start-issue NUM=1"; \ + exit 1; \ + fi + @echo "๐Ÿ” Starting work on issue #$(NUM)..." + @if [ -f "$(CURRENT_ISSUE_FILE)" ]; then \ + CURRENT=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.number // "unknown"'); \ + echo "โš ๏ธ Already working on issue #$$CURRENT"; \ + echo " Run 'make finish-issue' first or 'make workspace-status' to see details"; \ + exit 1; \ + fi + @if ! command -v curl >/dev/null 2>&1 || ! command -v jq >/dev/null 2>&1; then \ + echo "โŒ curl and jq required for workspace management"; \ + exit 1; \ + fi + @echo "๐Ÿ“‹ Fetching issue #$(NUM) details..." + @ISSUE_DATA=$$(curl -s "$(ISSUES_API)/$(NUM)" 2>/dev/null); \ + if echo "$$ISSUE_DATA" | jq -e '.title' >/dev/null 2>&1; then \ + mkdir -p "$(WORKSPACE_DIR)/issue_$(NUM)/tests"; \ + echo "$$ISSUE_DATA" | jq '{number: .number, title: .title, body: .body, state: .state, created_at: .created_at, html_url: .html_url}' > "$(CURRENT_ISSUE_FILE)"; \ + echo "$$ISSUE_DATA" | jq -r '"# Issue #" + (.number | tostring) + ": " + .title + "\n\n## Description\n" + .body + "\n\n## Requirements Breakdown\n\n- [ ] TODO: Break down requirements into testable scenarios\n- [ ] TODO: Identify edge cases\n- [ ] TODO: Define acceptance criteria\n\n## Test Plan\n\n- [ ] TODO: List specific test scenarios to implement\n"' > "$(WORKSPACE_DIR)/issue_$(NUM)/requirements.md"; \ + echo "# Test Plan for Issue #$(NUM)" > "$(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo "" >> "$(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo "## Test Scenarios" >> "$(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo "" >> "$(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo "- [ ] TODO: Add specific test scenarios" >> "$(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo "โœ… Workspace created for issue #$(NUM)"; \ + echo "๐Ÿ“ Workspace: $(WORKSPACE_DIR)/issue_$(NUM)/"; \ + echo "๐Ÿ“‹ Requirements: $(WORKSPACE_DIR)/issue_$(NUM)/requirements.md"; \ + echo "๐Ÿงช Test plan: $(WORKSPACE_DIR)/issue_$(NUM)/test_plan.md"; \ + echo ""; \ + echo "๐Ÿ’ก Next steps:"; \ + echo " 1. Review requirements.md and break down the issue"; \ + echo " 2. Plan test scenarios in test_plan.md"; \ + echo " 3. Use 'make add-test' to generate tests"; \ + echo " 4. Use 'make finish-issue' when complete"; \ + else \ + echo "โŒ Issue #$(NUM) not found or API error"; \ + echo " Use 'make list-open-issues' to see available issues"; \ + fi + +# Add test to current issue workspace +add-test: + @if [ ! -f "$(CURRENT_ISSUE_FILE)" ]; then \ + echo "โŒ No active issue workspace"; \ + echo " Run 'make start-issue NUM=X' first"; \ + exit 1; \ + fi + @if ! command -v claude >/dev/null 2>&1; then \ + echo "โŒ Claude Code not found - required for test generation"; \ + exit 1; \ + fi + @CURRENT_ISSUE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.number'); \ + ISSUE_TITLE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.title'); \ + ISSUE_BODY=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.body'); \ + echo "๐Ÿงช Adding test to issue #$$CURRENT_ISSUE workspace"; \ + echo ""; \ + echo "๐Ÿ“‹ Issue: $$ISSUE_TITLE"; \ + echo "๐Ÿ“ Workspace: $(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/"; \ + echo ""; \ + echo "๐Ÿค– Please ask Claude Code to generate a test:"; \ + echo ""; \ + echo " Command: 'Generate a test for the current workspace issue'"; \ + echo ""; \ + echo "๐Ÿ“ Test Requirements:"; \ + echo " - Save test in: $(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests/"; \ + echo " - Name format: test_issue_$$CURRENT_ISSUE_.py"; \ + echo " - Include docstring referencing issue #$$CURRENT_ISSUE"; \ + echo " - Follow TDD principles (test should fail initially)"; \ + echo " - Review requirements.md and test_plan.md for context"; \ + echo ""; \ + echo "๐Ÿ“‹ Issue Details:"; \ + echo " Title: $$ISSUE_TITLE"; \ + echo " Description: $$ISSUE_BODY"; \ + echo ""; \ + echo "๐Ÿ’ก After generation: Use 'make workspace-status' to see all tests" + +# Show current workspace status +workspace-status: + @if [ ! -f "$(CURRENT_ISSUE_FILE)" ]; then \ + echo "๐Ÿ“‹ No active issue workspace"; \ + echo " Use 'make start-issue NUM=X' to begin working on an issue"; \ + exit 0; \ + fi + @CURRENT_ISSUE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.number'); \ + ISSUE_TITLE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.title'); \ + ISSUE_STATE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.state'); \ + echo "๐Ÿ“‹ Active Issue Workspace"; \ + echo "========================"; \ + echo ""; \ + echo "๐ŸŽฏ Issue #$$CURRENT_ISSUE: $$ISSUE_TITLE"; \ + echo "๐Ÿ“Š Status: $$ISSUE_STATE"; \ + echo "๐Ÿ“ Workspace: $(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/"; \ + echo ""; \ + if [ -d "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests" ]; then \ + TEST_COUNT=$$(find "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests" -name "*.py" | wc -l); \ + echo "๐Ÿงช Generated Tests ($$TEST_COUNT):"; \ + if [ $$TEST_COUNT -gt 0 ]; then \ + find "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests" -name "*.py" -exec basename {} \; | sed 's/^/ - /'; \ + else \ + echo " - No tests generated yet"; \ + fi; \ + echo ""; \ + fi; \ + echo "๐Ÿ“‹ Workspace Files:"; \ + echo " - requirements.md (review and break down issue)"; \ + echo " - test_plan.md (plan test scenarios)"; \ + echo " - tests/ (generated test files)"; \ + echo ""; \ + echo "๐Ÿ’ก Commands:"; \ + echo " - make add-test (generate another test)"; \ + echo " - make finish-issue (complete and move tests to main)" + +# Complete issue work (move tests to main and cleanup) +finish-issue: + @if [ ! -f "$(CURRENT_ISSUE_FILE)" ]; then \ + echo "โŒ No active issue workspace"; \ + echo " Nothing to finish"; \ + exit 1; \ + fi + @CURRENT_ISSUE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.number'); \ + ISSUE_TITLE=$$(cat "$(CURRENT_ISSUE_FILE)" | jq -r '.title'); \ + echo "๐Ÿ Finishing work on issue #$$CURRENT_ISSUE"; \ + echo ""; \ + if [ -d "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests" ]; then \ + TEST_COUNT=$$(find "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests" -name "*.py" | wc -l); \ + if [ $$TEST_COUNT -gt 0 ]; then \ + echo "๐Ÿ“ฆ Moving $$TEST_COUNT test(s) to tests/ directory..."; \ + cp $(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE/tests/*.py tests/ 2>/dev/null || echo " No .py files to move"; \ + echo "โœ… Tests moved to main tests/ directory"; \ + else \ + echo "โš ๏ธ No tests found in workspace"; \ + fi; \ + fi; \ + echo "๐Ÿงน Cleaning up workspace..."; \ + rm -rf "$(WORKSPACE_DIR)/issue_$$CURRENT_ISSUE"; \ + rm -f "$(CURRENT_ISSUE_FILE)"; \ + echo "โœ… Issue #$$CURRENT_ISSUE workspace cleaned up"; \ + echo ""; \ + echo "๐Ÿ’ก Next steps:"; \ + echo " - Run 'make test' to verify tests fail (red state)"; \ + echo " - Implement code to make tests pass (green state)"; \ + echo " - Start next issue with 'make start-issue NUM=X'"