coulomb/issue-core
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Projects Releases Wiki Activity

Refresh agent instruction files

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 16:55:43 +02:00
parent b20eb11583
commit 2fd7de08d2
10 changed files with 383 additions and 400 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.claude/rules/agents.md Normal file
View File

@@ -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.

8
.claude/rules/architecture.md Normal file
View File

@@ -0,0 +1,8 @@
## Architecture
<!-- TODO: Describe the key design decisions and component structure.
Key modules, data flows, external integrations, state machines, etc. -->
## Quick Reference
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference

38
.claude/rules/first-session.md Normal file
View File

@@ -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-<slug>.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="<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}
)
```
<!-- Delete or archive this file once past first session -->

8
.claude/rules/repo-boundary.md Normal file
View File

@@ -0,0 +1,8 @@
## Repo boundary
This repo owns **issue-core** only. It does not own:
<!-- TODO: List what belongs in adjacent repos, e.g.:
- SSH key management → railiance-infra/
- State hub code → state-hub/
-->

5
.claude/rules/repo-identity.md Normal file
View File

@@ -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

84
.claude/rules/session-protocol.md Normal file
View File

@@ -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/<id>/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="<uuid>")
```
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":"<uuid>","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 <repo_path> 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.

19
.claude/rules/stack-and-commands.md Normal file
View File

@@ -0,0 +1,19 @@
## Stack
<!-- TODO: Fill in language, frameworks, and key dependencies -->
- **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)
```

28
.claude/rules/workplan-convention.md Normal file
View File

@@ -0,0 +1,28 @@
## Workplan Convention (ADR-001)
File location: `workplans/issue-core-WP-NNNN-<slug>.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-<slug>.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.
<!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

162
AGENTS.md Normal file
View File

@@ -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/<id>/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": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-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/<task_id>" \
-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-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-ISSUE-WP-NNNN-<slug>.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: "<uuid>" # 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: "<uuid>" # 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/`)

411
CLAUDE.md
View File

@@ -1,400 +1,11 @@
# CLAUDE.md # issue-core — Claude Code Instructions
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. @SCOPE.md
@.claude/rules/repo-identity.md
## Project Overview @.claude/rules/session-protocol.md
@.claude/rules/first-session.md
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. @.claude/rules/workplan-convention.md
@.claude/rules/stack-and-commands.md
## Development Commands @.claude/rules/architecture.md
@.claude/rules/repo-boundary.md
### Installation & Setup @.claude/rules/agents.md
- 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 <number>` - Show issue details
- `issue create "Title"` - Create new issue
- `issue close <number>` - 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/<name>/`
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.