# LeanKG Development Workflow for OpenCode AI Agent
## Overview
This document defines the workflow pattern for OpenCode AI agent to implement features in LeanKG. Each feature implementation follows a structured process: **Update Docs → Implement → Test → Commit → Push**.
## Core Principle: One Feature Per Commit
Every distinct feature or fix should be:
1. Documented before implementation
2. Implemented in isolation
3. Tested
4. Committed with a clear message
5. Pushed before starting the next feature
---
## Standard Feature Implementation Workflow
### Step 0: Understand the Task
Before doing anything:
1. Explore the codebase to understand current structure
2. Read existing relevant code and documentation
3. Understand the data models and relationships
4. Identify where changes need to be made
```bash
# Use explore agent for large-scale understanding
task(description="Explore LeanKG codebase", subagent_type="explore", prompt="...")
# Use Read/grep for targeted understanding
read(filePath="src/db/models.rs")
grep(pattern="BusinessLogic", path="src")
```
### Step 1: Update Documentation (PRD → HLD → README)
**Always update documentation BEFORE writing any code.**
#### 1.1 Update PRD (`docs/requirement/prd-leankg.md`)
- Bump version number and update changelog
- Add new User Story (US-XX)
- Add new Functional Requirements (FR-XX)
- Update roadmap if needed
- Add new terms to glossary
```markdown
**Changelog:**
- v1.X - New Feature: Feature name
- US-XX: User story description
- FR-XX to FR-XX: New functional requirements
```
#### 1.2 Update HLD (`docs/design/hld-leankg.md`)
- Update version and changelog
- Update C4 Container diagram with new components
- Add new component to component table
- Add new data flow diagrams (sequence diagrams)
- Add new relationship types to data model
- Add new CLI commands and MCP tools to interface specs
- Update glossary with new terms
#### 1.3 Update README
- Add feature to Features table
- Add new CLI commands to CLI Commands table
- Add new MCP tools to MCP Tools table
- Update verification status table
- Update project structure if adding new modules
### Step 2: Implement the Feature
#### 2.1 For New Modules
```bash
# Create module directory
mkdir -p src/new_module/
```
Create `src/new_module/mod.rs` with:
- Data structures (models)
- Public API functions
- Integration with existing modules
#### 2.2 For Existing Modules
Follow existing code patterns:
- Use same error handling style
- Match naming conventions
- Follow existing function signatures
#### 2.3 Key Files to Modify
| `src/lib.rs` | Add `pub mod new_module;` |
| `Cargo.toml` | Add dependencies |
| `src/db/models.rs` | Add new data structures |
| `src/db/mod.rs` | Add database operations |
| `src/graph/query.rs` | Add graph query methods |
| `src/mcp/tools.rs` | Add MCP tool definitions |
| `src/mcp/handler.rs` | Add tool execution handlers |
### Step 3: Build and Test
```bash
# Build to catch compilation errors
# If errors, fix them and rebuild
# Common issues:
# - Missing imports
# - Private field access (add getter methods to GraphEngine)
# - Type mismatches
# - Method not found errors
# Run tests
# Fix any failing tests
```
### Step 4: Commit with Clear Message
Follow conventional commit format:
```bash
git add -A
Detailed explanation of what was done.
- Added new functionality X
- Fixed issue Y
- Updated Z"
```
**Commit types:**
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only
- `chore:` Build/tooling changes
### Step 5: Push
```bash
# Always pull first to handle remote changes
git pull origin master --rebase
# If conflicts, resolve them:
# 1. Edit conflicted files
# 2. git add <file>
# 3. GIT_EDITOR="cat" git rebase --continue
git push origin master
```
---
## LeanKG-Specific Patterns
### Adding a New Data Model
1. Add struct to `src/db/models.rs`:
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NewModel {
pub id: Option<String>,
pub name: String,
pub related_qualified: Option<String>,
pub metadata: serde_json::Value,
}
```
2. Add database operations to `src/db/mod.rs`
3. Add query methods to `src/graph/query.rs`
### Adding a New Relationship Type
1. Store relationship with descriptive metadata:
```rust
relationships.push(Relationship {
id: None,
source_qualified: source,
target_qualified: target,
rel_type: "new_relationship".to_string(),
metadata: serde_json::json!({
"context": "description",
"line": line_number,
}),
});
```
### Adding a New MCP Tool
1. Define tool in `src/mcp/tools.rs`:
```rust
ToolDefinition {
name: "new_tool".to_string(),
description: "Description".to_string(),
input_schema: json!({
"type": "object",
"properties": {
"param": {"type": "string"}
}
}),
}
```
2. Add handler method in `src/mcp/handler.rs`:
```rust
fn new_tool(&self, args: &Value) -> Result<Value, String> {
let param = args["param"].as_str().ok_or("Missing 'param'")?;
// Implementation
Ok(json!({ "result": result }))
}
```
3. Add match arm in `execute_tool`:
```rust
"new_tool" => self.new_tool(arguments),
```
### Adding CLI Commands
CLI commands are defined in `src/cli/mod.rs` using Clap. Follow existing command patterns.
---
## Handling Git Rebase Conflicts
When `git pull --rebase` shows conflicts:
```bash
# See conflicted files
git diff --name-only --diff-filter=U
# View conflict
# Read file to see conflict markers
read(filePath="README.md", offset=100, limit=50)
# Edit to resolve conflict
edit(filePath="README.md", oldString="<<<<<<< HEAD\n=======\n<<<<<<< commit", newString="resolved content")
# Continue rebase
git add README.md
GIT_EDITOR="cat" git rebase --continue
```
---
## Quality Checklist
Before committing, verify:
- [ ] Documentation updated (PRD, HLD, README)
- [ ] Code compiles without errors
- [ ] Tests pass
- [ ] New code follows existing patterns
- [ ] No debug/placeholder code left in
- [ ] Commit message is clear
- [ ] Pulled latest remote changes
- [ ] Pushed successfully
---
## Example: Complete Feature Workflow
```bash
# 1. Understand
task(description="Explore db module", prompt="Explore src/db/ to understand data models...")
# 2. Update docs first
edit(filePath="docs/requirement/prd-leankg.md", oldString="...", newString="...")
edit(filePath="docs/design/hld-leankg.md", oldString="...", newString="...")
edit(filePath="README.md", oldString="...", newString="...")
# 3. Implement
write(content="...", filePath="src/new_module/mod.rs")
edit(filePath="src/lib.rs", oldString="...", newString="...")
# 4. Build and test
cargo build
cargo test
# 5. Commit
git add -A
git commit -m "feat: Add new feature
- Added new module for X
- Implemented Y functionality
- Added Z relationship type"
# 6. Push
git pull origin master --rebase
git push origin master
```
---
## Quick Reference Commands
```bash
# Build
# Test
# Full test with output
cargo test 2>&1
# Check git status
git status
# See recent commits
git log --oneline -5
# Stash changes
git stash
# Pop stash
git stash pop
```
---
## Document Revision
**Version:** 1.0
**Date:** 2026-03-25
**Based on:** LeanKG Phase 2 implementation session