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

411
CLAUDE.md
View File

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