From 2fd7de08d2b9ae24034d017b16ee66b6dec87caf Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 18 May 2026 16:55:43 +0200 Subject: [PATCH] Refresh agent instruction files --- .claude/rules/agents.md | 20 ++ .claude/rules/architecture.md | 8 + .claude/rules/first-session.md | 38 +++ .claude/rules/repo-boundary.md | 8 + .claude/rules/repo-identity.md | 5 + .claude/rules/session-protocol.md | 84 ++++++ .claude/rules/stack-and-commands.md | 19 ++ .claude/rules/workplan-convention.md | 28 ++ AGENTS.md | 162 +++++++++++ CLAUDE.md | 411 +-------------------------- 10 files changed, 383 insertions(+), 400 deletions(-) create mode 100644 .claude/rules/agents.md create mode 100644 .claude/rules/architecture.md create mode 100644 .claude/rules/first-session.md create mode 100644 .claude/rules/repo-boundary.md create mode 100644 .claude/rules/repo-identity.md create mode 100644 .claude/rules/session-protocol.md create mode 100644 .claude/rules/stack-and-commands.md create mode 100644 .claude/rules/workplan-convention.md create mode 100644 AGENTS.md diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -0,0 +1,20 @@ +## Kaizen Agents + +Specialized agent personas available on demand via the state-hub MCP. + +**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category +**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them + +Common agents: + +| Agent | Category | When to use | +|-------|----------|-------------| +| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature | +| `code-refactoring` | quality | Code quality analysis and safe refactoring | +| `test-maintenance` | testing | Diagnose and fix failing tests | +| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | +| `keepaTodofile` | process | Maintain TODO.md during work | +| `project-management` | process | Track status, determine next steps | +| `datamodel-optimization` | quality | Optimize dataclasses and data structures | + +All 17 agents: call `list_kaizen_agents()` for the full list. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..7c2a645 --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,8 @@ +## Architecture + + + +## Quick Reference + +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..dde0fa4 --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,38 @@ +## First Session Protocol + +Triggered when `get_domain_summary("custodian")` shows **no workstreams**. +The project is registered but work has not yet been structured. + +**Step 1 — Read, don't write** +- `~/the-custodian/canon/projects/custodian/project_charter_v0.1.md` — purpose, scope +- `~/the-custodian/canon/projects/custodian/roadmap_v0.1.md` — planned phases +- Scan repo root: README, directory structure, existing code or docs + +**Step 2 — Survey in-progress work** +Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete. + +**Step 3 — Propose workstreams to Bernd** +Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a +roadmap phase. **Wait for approval before creating.** + +**Step 4 — Create workplan file first, then DB record (ADR-001)** +``` +workplans/issue-core-WP-NNNN-.md ← write this first +``` +Then register in the hub: +``` +create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...") +create_task(workstream_id="", title="...", priority="high|medium|low") +``` + +**Step 5 — Record the setup** +``` +add_progress_event( + summary="First session: structured custodian into N workstreams, M tasks", + event_type="milestone", + topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", + detail={"workstreams": [...], "tasks_created": M} +) +``` + + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..f01ed1f --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,8 @@ +## Repo boundary + +This repo owns **issue-core** only. It does not own: + + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..d9d5634 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**Purpose:** Authoritative task lifecycle manager for the Coulomb org. Backend-agnostic CLI + REST ingestion endpoint for tasks from activity-core's IssueSink. Pluggable backends (Gitea, SQLite, GitHub). Renamed from issue-facade on 2026-05-17. + +**Domain:** custodian +**Repo slug:** issue-core +**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..52eb3be --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,84 @@ +## Session Protocol + +State Hub: http://127.0.0.1:8000 + +**Step 1 — Orient** + +Read the offline-safe brief first — it works without a live hub connection: +```bash +cat .custodian-brief.md +``` +Then call the MCP tool for richer cross-domain context when MCP tools are exposed: +``` +get_domain_summary("custodian") +``` +If MCP tools are unavailable in the current agent session, use the REST API: +```bash +curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool +``` +If the hub is offline: `cd ~/state-hub && make api` + +**Step 2 — Check inbox** +With MCP tools: +``` +get_messages(to_agent="issue-core", unread_only=True) +``` +Mark read with `mark_message_read(message_id)`. Reply or act on coordination +requests before proceeding. + +Without MCP tools: +```bash +curl -s "http://127.0.0.1:8000/messages/?to_agent=issue-core&unread_only=true" \ + | python3 -m json.tool +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +**Step 3 — Scan workplans** +```bash +ls workplans/ +``` +For each file with `status: ready`, `active`, or `blocked`, note pending +`todo`/`in_progress` tasks. + +**Step 4 — Present brief** + +1. **Active workstreams** for `custodian` — title, task counts, blocking decisions +2. **Pending tasks** from `workplans/` + any `[repo:issue-core]` hub tasks +3. **Goal guidance** — if `goal_guidance` in summary: + - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* + - `alignment_warnings`: flag if active work is not aligned with current goal +4. **Suggested next action** — highest-priority open item +5. **SBOM status** — flag if `last_sbom_at` is unset for this repo + +If no workstreams: follow First Session Protocol (`first-session.md`). + +**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` + +> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) +> are First Session Protocol only. Work structure belongs in repo files (ADR-001). + +**Session close:** +With MCP tools: +``` +add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="") +``` +Without MCP tools: +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' +``` +If workplan files were modified, ensure the local copy is up to date first: +```bash +git -C pull --ff-only +cd ~/state-hub && make fix-consistency REPO=issue-core +``` +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the combined target which pulls before fixing: +```bash +cd ~/state-hub && make fix-consistency-remote REPO=issue-core +``` +**C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback +will sync the file to match DB. **C-16** (repo behind remote) blocks all writes +until you pull — intentional to prevent clobbering remote progress. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..dc53ac6 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,19 @@ +## Stack + + +- **Language:** +- **Key deps:** + +## Dev Commands + +```bash +# TODO: Fill in the standard commands for this repo + +# Install dependencies + +# Run tests + +# Lint / type check + +# Build / package (if applicable) +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..14ca3e5 --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,28 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/issue-core-WP-NNNN-.md` +ID prefix: `ISSUE-WP` + +Work items originate as files in this repo **before** being registered in the hub. + +Canonical workplan/workstream frontmatter statuses are: +`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. +Use `proposed` for a newly drafted plan, `ready` after review against current +repo state, and `finished` when implementation is complete. `stalled` and +`needs_review` are derived health labels, not stored statuses. + +Closed workplans may be moved to `workplans/archived/` with a completion-date +prefix: `YYMMDD-issue-core-WP-NNNN-.md`. The frontmatter id remains +unchanged; the prefix is only for quick visual reference. + +Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: +`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids +`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed +directly. Promote anything requiring analysis, design, approval, dependencies, or +multiple planned phases into a normal workplan. + +Ecosystem todos from other agents arrive as `[repo:issue-core]` hub tasks — +visible at session start. Pick one up by creating the workplan file, then registering +the workstream. + + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..11b1524 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,162 @@ +# issue-core — Agent Instructions + +## Repo Identity + +**Purpose:** Authoritative task lifecycle manager for the Coulomb org. Backend-agnostic CLI + REST ingestion endpoint for tasks from activity-core's IssueSink. Pluggable backends (Gitea, SQLite, GitHub). Renamed from issue-facade on 2026-05-17. + +**Domain:** custodian +**Repo slug:** issue-core +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `ISSUE-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=issue-core&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "in_progress"}' +# values: todo | in_progress | done | blocked +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=issue-core&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check blocked tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=issue-core + ``` + This syncs task status from files into the hub DB. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/ISSUE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-ISSUE-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: ISSUE-WP-NNNN +type: workplan +title: "..." +domain: custodian +repo: issue-core +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: ISSUE-WP-NNNN-T01 +status: todo | in_progress | done | blocked +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `in_progress` → `done` (or `blocked`) + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=issue-core` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md index 75b9e16..c9ae1b2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,400 +1,11 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -Issue Core is a universal CLI for issue tracking that provides a unified interface to multiple issue tracking backends (GitHub, GitLab, Gitea, local SQLite). It implements the **Facade Pattern** to abstract away differences between various issue tracking systems, providing developers with a consistent CLI experience regardless of the underlying backend. - -## Development Commands - -### Installation & Setup -- Install for development: `pip install -e ".[dev]"` -- Install production: `pip install -e .` -- Clean build artifacts: `make issue-core-clean` - -### Testing -- Run all tests: `pytest tests/` -- Run specific test file: `pytest tests/test_gitea_backend.py` -- Run with coverage: `pytest tests/ --cov=issue_core --cov-report=html --cov-report=term` -- Run integration tests: `pytest tests/test_gitea_integration.py -v` - -### Code Quality -- Run linter: `make issue-core-lint` -- Format code: `black issue_core/ tests/` (line length: 100) -- Sort imports: `isort issue_core/ tests/` - -### CLI Usage -The project provides two entry points: `issue` and `issue-core` (both execute `issue_core.cli.main:main`) - -Common commands: -- `issue list` - List issues -- `issue show ` - Show issue details -- `issue create "Title"` - Create new issue -- `issue close ` - Close issue -- `issue backend list` - List configured backends -- `issue sync` - Synchronize with remote backend - -## Architecture - -### Core Design Pattern: Facade with Plugin Architecture - -The codebase implements a **plugin-based facade pattern** with clear separation of concerns: - -``` -┌─────────────────────────────────────────┐ -│ CLI Layer (Click) │ -│ issue_core/cli/*.py │ -└───────────────┬─────────────────────────┘ - │ -┌───────────────▼─────────────────────────┐ -│ Core Domain Models │ -│ issue_core/core/models.py │ -│ (Issue, Label, User, etc.) │ -└───────────────┬─────────────────────────┘ - │ -┌───────────────▼─────────────────────────┐ -│ Backend Interface (ABC) │ -│ issue_core/core/interfaces.py │ -│ IssueBackend, LocalBackend, │ -│ RemoteBackend, SyncableBackend │ -└───────────────┬─────────────────────────┘ - │ - ┌───────┴────────┐ - │ │ -┌───────▼──────┐ ┌──────▼───────┐ -│Local Backend │ │Gitea Backend │ -│ (SQLite) │ │ (REST API) │ -└──────────────┘ └──────────────┘ -``` - -### Key Components - -#### 1. Core Domain Models (`issue_core/core/models.py`) -- **Issue**: Universal issue model with state management, label categorization, and domain logic -- **Label**: Supports categorization (priority/type/status/other) with cached properties -- **User, Milestone, Comment**: Supporting models -- **IssueState, Priority, IssueType**: Enumerations with backend mapping - -The Issue model uses `@cached_property` for performance optimization and includes domain logic methods (`close()`, `reopen()`, `add_label()`, etc.) that enforce business rules. - -#### 2. Backend Interface (`issue_core/core/interfaces.py`) -- **IssueBackend (ABC)**: Defines the contract all backends must implement -- **LocalBackend, RemoteBackend**: Marker interfaces for backend categorization -- **SyncableBackend**: Interface for backends supporting synchronization -- **BackendCapabilities**: Describes feature support per backend -- **BackendFactory**: Registry pattern for backend creation - -**Critical**: All backends MUST implement the full `IssueBackend` interface. The interface includes: -- Connection management: `connect()`, `disconnect()`, `test_connection()` -- CRUD operations: `create_issue()`, `get_issue()`, `update_issue()`, `delete_issue()` -- Query operations: `list_issues()`, `search_issues()` -- Label, User, Milestone, Comment operations -- Optional: `bulk_update_issues()` (if capabilities support it) - -#### 3. Backend Implementations - -**Local Backend** (`issue_core/backends/local/backend.py`): -- Uses SQLite with schema defined in `schema.sql` -- Full offline functionality -- Serves as synchronization source of truth -- Implements `LocalBackend` and `SyncableBackend` - -**Gitea Backend** (`issue_core/backends/gitea/backend.py`): -- REST API integration with Gitea instances -- Rate limiting and error handling -- ID mapping between local and remote issues -- Implements `RemoteBackend` and `SyncableBackend` - -#### 4. CLI Layer (`issue_core/cli/`) -- **main.py**: Entry point, Click group setup, command registration -- **commands.py**: Core issue operations (list, show, create, close) -- **backend_commands.py**: Backend management (add, list, switch) -- **sync_commands.py**: Synchronization operations -- **utils.py**: Helper functions for formatting and backend access - -### ID Mapping Strategy - -The system uses a **dual-ID approach** for cross-backend synchronization: - -- `id`: Universal ID (UUID for local, external ID for remote) -- `number`: Human-readable sequential number (user-facing) -- `backend_id`: Backend-specific identifier for sync - -When syncing, backends maintain mappings between local numbers and remote IDs. The Gitea backend stores this in `sync_metadata` on the Issue model. - -### State Management - -`IssueState` enum provides universal states with backend-specific mapping via `to_backend_string()`: -- OPEN, CLOSED, IN_PROGRESS, BLOCKED -- Some backends (like Gitea) only support OPEN/CLOSED, so IN_PROGRESS and BLOCKED map to OPEN - -## Testing Strategy - -### Test Organization -- `test_gitea_backend.py`: Unit tests for Gitea backend with mocked API -- `test_gitea_integration.py`: Full integration tests with real Gitea instance -- `test_cli_commands.py`: CLI command testing - -### Integration Tests -The integration tests (`test_gitea_integration.py`) expect a Gitea instance at `http://localhost:3000` with test credentials. They create a temporary test repository, run full CRUD operations, and clean up afterwards. - -**Important**: Integration tests use pytest markers: -- `@pytest.mark.integration` - Integration tests (slower) -- `@pytest.mark.unit` - Unit tests (fast) - -Run only unit tests: `pytest -m unit` -Run only integration tests: `pytest -m integration` - -## Common Development Tasks - -### Adding a New Backend - -1. Create backend package in `issue_core/backends//` -2. Implement `IssueBackend` interface (or extend `LocalBackend`/`RemoteBackend`) -3. Implement all abstract methods from the interface -4. Define `BackendCapabilities` to specify supported features -5. Register backend in `BackendFactory` (typically in `__init__.py`) -6. Add configuration handling in CLI backend commands -7. Write unit tests with mocked external dependencies -8. Write integration tests if applicable - -### Modifying the Issue Model - -When changing `issue_core/core/models.py`: -1. Update the `Issue` dataclass definition -2. Update `to_dict()` serialization method -3. Invalidate caches if adding/modifying label-dependent properties -4. Update all backend implementations to handle new fields -5. Update database schema in `backends/local/schema.sql` -6. Write migration logic if modifying existing fields - -### Adding CLI Commands - -1. Add command function in appropriate file (`commands.py`, `backend_commands.py`, etc.) -2. Use `@click.command()` decorator with appropriate options -3. Call `get_backend(ctx)` to retrieve the active backend -4. Use `format_issue()` or `format_issue_list()` from `utils.py` for consistent output -5. Handle errors with `raise click.ClickException(message)` -6. Register command in `main.py` if creating new command group - -## Configuration - -### Project Configuration (`pyproject.toml`) -- Entry points: `issue` and `issue-core` commands -- Dependencies: click, requests, python-dateutil -- Optional dependencies: dev, docs, gitea, github, jira -- Code style: Black (line-length=100), isort (profile="black") -- Test markers: unit, integration, slow - -### Makefile Integration -The capability integrates with the parent markitect project via `Makefile`: -- Prefixed targets: `issue-core-*` for development commands -- Unprefixed targets: `issue-*` for user-facing CLI operations -- Uses `pip install -e` for editable installation - -## Important Patterns and Conventions - -### Error Handling -- Backend-specific errors inherit from base exceptions (e.g., `GiteaAPIError`) -- CLI commands convert exceptions to `click.ClickException` with user-friendly messages -- Use specific exception types for rate limiting, authentication, network issues - -### Type Hints -- Mypy strict mode enabled (`disallow_untyped_defs = true`) -- All functions must have type annotations -- Use `Optional[T]` for nullable types -- Use `List[T]`, `Dict[K, V]` from `typing` module (Python 3.8 compatibility) - -### Performance Optimizations -- Use `@cached_property` for expensive computations (e.g., label categorization) -- Call `invalidate_cache()` when modifying cached data -- Single-pass algorithms for label categorization in Issue model - -### Synchronization -When implementing sync: -1. Local backend is source of truth -2. Remote backends track last sync timestamp -3. Use `get_issues_modified_since()` for incremental sync -4. Handle conflicts via `SyncableBackend.resolve_sync_conflict()` -5. Store sync metadata in Issue.sync_metadata dict - -## Dependencies and External Systems - -### Runtime Dependencies -- **click**: CLI framework (>=8.0.0) -- **requests**: HTTP client for remote backends (>=2.25.0) -- **python-dateutil**: Date/time parsing (>=2.8.0) - -### Development Dependencies -- **pytest**: Testing framework with markers support -- **pytest-cov**: Coverage reporting -- **pytest-mock**: Mocking utilities -- **black, isort, flake8, mypy**: Code quality tools - -### External Systems -- **Gitea API**: REST API at `/api/v1/` endpoints -- **SQLite**: Local database (no server required) -- Future: GitHub API, GitLab API, JIRA API - -## Repository Context - -This is a capability within the larger markitect project (`/capabilities/issue-core/`). The capability: -- Can be installed independently via `pip install -e .` -- Integrates with parent project via Makefile targets -- Follows markitect capability conventions for structure and naming - -## Feedback and Continuous Improvement - -This capability implements the **feedback pattern** - a lightweight, unstructured feedback loop for continuous improvement based on real-world usage from master projects integrating this capability. - -### Overview - -The feedback system consists of: -- **`feedback/` directory**: Stores all feedback with minimal organization -- **`.capability/feedback` CLI tool**: Standalone tool for submitting and managing feedback -- **No structure imposement**: Accept any text/markdown format -- **Capability-owned**: Maintainers organize and prioritize feedback - -### Directory Structure - -``` -feedback/ -├── inbound/ # New feedback from users (unreviewed) -├── reviewed/ # Feedback reviewed by maintainers -├── archived/ # Resolved or outdated feedback -└── README.md # Complete documentation -``` - -### For Users: Submitting Feedback - -Users of issue-core (master projects integrating it) can submit feedback in multiple ways: - -**Option 1: Using feedback CLI** -```bash -# Quick text feedback -./.capability/feedback submit "The sync command is slow with 1000+ issues" - -# From a file -./.capability/feedback submit detailed-feedback.md - -# With metadata -./.capability/feedback submit "Bug report" --category=bug --contact=me@email.com -``` - -**Option 2: Direct file drop (no CLI needed)** -```bash -# Just create a markdown file in inbound/ -cat > feedback/inbound/$(date +%Y%m%d)-sync-issue.md << 'EOF' -The sync is taking 10+ minutes with our 5000-issue repo. -Would love to see progress indicators or batch processing. -EOF -``` - -**Option 3: From master project** -```bash -cd my-master-project -echo "Feedback about issue-core..." > feedback.md -cp feedback.md capabilities/issue-core/feedback/inbound/$(date +%Y%m%d)-feedback.md -``` - -### For Maintainers: Processing Feedback - -**List and review feedback:** -```bash -# List pending feedback -./.capability/feedback list - -# Show specific feedback -./.capability/feedback show 20251217-103045-abc12345.md - -# Show statistics -./.capability/feedback stats -``` - -**Process feedback:** -```bash -# Mark as reviewed -./.capability/feedback review 20251217-103045-abc12345.md - -# Create issue from feedback -./.capability/feedback review 20251217-103045-abc12345.md --create-issue - -# Archive when resolved -./.capability/feedback archive 20251217-103045-abc12345.md -``` - -**Manual workflow (without CLI):** -```bash -# 1. List new feedback -ls -lt feedback/inbound/ - -# 2. Read feedback -cat feedback/inbound/20251217-103045-sync-issue.md - -# 3. Take action (create issue, fix, document) -issue create "Feature: Show sync progress" \ - --description "$(cat feedback/inbound/20251217-103045-sync-issue.md)" \ - --label=feedback --label=feature - -# 4. Move to reviewed -mv feedback/inbound/20251217-103045-sync-issue.md feedback/reviewed/ -``` - -### Integration with Development Workflow - -Feedback informs: -- **Roadmap prioritization**: Most requested features get priority -- **Bug triage**: Real-world issues from production usage -- **Documentation improvements**: Where users struggle -- **UX enhancements**: Friction points in actual usage - -**Review rhythm:** -- Daily: Quick scan of new feedback -- Weekly: Deep review, create issues, respond to users -- Monthly: Archive old feedback, analyze trends - -### Feedback Pattern (Reusable Across Capabilities) - -The feedback system is **capability-agnostic** and can be copied to any markitect capability: - -1. **Copy the pattern:** - ```bash - mkdir -p feedback/inbound feedback/reviewed feedback/archived - cp /path/to/feedback-template/README.md feedback/ - cp /path/to/feedback-template/feedback .capability/ - chmod +x .capability/feedback - ``` - -2. **Document in CAPABILITY-issue-tracking.yaml:** - ```yaml - feedback: - enabled: true - method: feedback-capability - submission: - cli: ".capability/feedback submit 'Your feedback'" - directory: "feedback/inbound/" - ``` - -3. **Add to Makefile (optional):** - ```makefile - feedback: - @./.capability/feedback submit "$(MSG)" - ``` - -**Future Evolution:** -- When capability becomes a service, add API endpoint: `POST /api/feedback` -- API writes to same `feedback/inbound/` directory -- Maintains consistency across CLI, file drop, and API submission - -### Why This Pattern? - -- **Decentralized**: Each capability owns its feedback -- **Flexible**: No forms, no required structure -- **Durable**: Plain files survive system changes -- **Auditable**: Git tracks all feedback -- **Actionable**: Feedback lives where maintainers work -- **Scalable**: Works for 1 user or 1000 users -- **Future-proof**: Can evolve to CLI/API while maintaining structure - -See `feedback/README.md` for complete documentation. +# issue-core — Claude Code Instructions + +@SCOPE.md +@.claude/rules/repo-identity.md +@.claude/rules/session-protocol.md +@.claude/rules/first-session.md +@.claude/rules/workplan-convention.md +@.claude/rules/stack-and-commands.md +@.claude/rules/architecture.md +@.claude/rules/repo-boundary.md +@.claude/rules/agents.md