personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: remove Wiki.js references from architecture docs

Browse Source 
- Updated agent-workflow.spec.md to use Gitea Wiki instead of Wiki.js
- Updated component-map.spec.md to show Gitea (Issues + Wiki) as single service
- Changed GraphQL references to REST API (Gitea uses REST)
- Added Code Reviewer agent swimlane to agent-workflow diagram
- Added ARCHITECTURE NOTES sections to clarify current design

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-20 11:22:20 -05:00
parent 70d3933da4
commit 14425cfad1
2 changed files with 164 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

200
docs/architecture/agent-workflow.spec.md
View File

@@ -2,7 +2,7 @@
**Target File:** `docs/architecture/agent-workflow.drawio` **Target File:** `docs/architecture/agent-workflow.drawio`
**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle. **Purpose:** Shows when Planner, Orchestrator, Executor, and Code Reviewer agents trigger during sprint lifecycle.
**Diagram Type:** Swimlane / Sequence Diagram **Diagram Type:** Swimlane / Sequence Diagram
@@ -16,8 +16,8 @@
| planner-lane | Planner Agent | #4A90D9 | 2 | | planner-lane | Planner Agent | #4A90D9 | 2 |
| orchestrator-lane | Orchestrator Agent | #7CB342 | 3 | | orchestrator-lane | Orchestrator Agent | #7CB342 | 3 |
| executor-lane | Executor Agent | #FF9800 | 4 | | executor-lane | Executor Agent | #FF9800 | 4 |
| gitea-lane | Gitea | #9E9E9E | 5 | | reviewer-lane | Code Reviewer Agent | #9C27B0 | 5 |
| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) | | gitea-lane | Gitea (Issues + Wiki) | #9E9E9E | 6 (rightmost) |
--- ---
@@ -30,7 +30,7 @@
| p1-start | /sprint-plan | rounded-rect | user-lane | 1 | | p1-start | /sprint-plan | rounded-rect | user-lane | 1 |
| p1-activate | Planner Activates | rectangle | planner-lane | 2 | | p1-activate | Planner Activates | rectangle | planner-lane | 2 |
| p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 | | p1-search-lessons | Search Lessons Learned | rectangle | planner-lane | 3 |
| p1-wikijs-query | Query Past Lessons | rectangle | wikijs-lane | 4 | | p1-gitea-wiki-query | Query Past Lessons (Wiki) | rectangle | gitea-lane | 4 |
| p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 | | p1-return-lessons | Return Relevant Lessons | rectangle | planner-lane | 5 |
| p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 | | p1-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 |
| p1-user-answers | Provide Answers | rectangle | user-lane | 7 | | p1-user-answers | Provide Answers | rectangle | user-lane | 7 |
@@ -44,8 +44,8 @@
|------|----|-------|-------| |------|----|-------|-------|
| p1-start | p1-activate | invokes | solid | | p1-start | p1-activate | invokes | solid |
| p1-activate | p1-search-lessons | | solid | | p1-activate | p1-search-lessons | | solid |
| p1-search-lessons | p1-wikijs-query | GraphQL search | solid | | p1-search-lessons | p1-gitea-wiki-query | REST API (search_lessons) | solid |
| p1-wikijs-query | p1-return-lessons | lessons data | dashed | | p1-gitea-wiki-query | p1-return-lessons | lessons data | dashed |
| p1-return-lessons | p1-clarify | | solid | | p1-return-lessons | p1-clarify | | solid |
| p1-clarify | p1-user-answers | questions | solid | | p1-clarify | p1-user-answers | questions | solid |
| p1-user-answers | p1-clarify | answers | dashed | | p1-user-answers | p1-clarify | answers | dashed |
@@ -65,7 +65,7 @@
| p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 | | p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 |
| p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 | | p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 |
| p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 | | p2-gitea-list | List Open Issues | rectangle | gitea-lane | 14 |
| p2-sequence | Sequence Work | rectangle | orchestrator-lane | 15 | | p2-sequence | Sequence Work (Dependencies) | rectangle | orchestrator-lane | 15 |
| p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 | | p2-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 | | p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
| p2-implement | Implement Task | rectangle | executor-lane | 18 | | p2-implement | Implement Task | rectangle | executor-lane | 18 |
@@ -83,7 +83,7 @@
| p2-orch-activate | p2-fetch-issues | | solid | | p2-orch-activate | p2-fetch-issues | | solid |
| p2-fetch-issues | p2-gitea-list | REST API | solid | | p2-fetch-issues | p2-gitea-list | REST API | solid |
| p2-gitea-list | p2-sequence | issues data | dashed | | p2-gitea-list | p2-sequence | issues data | dashed |
| p2-sequence | p2-dispatch | | solid | | p2-sequence | p2-dispatch | parallel batching | solid |
| p2-dispatch | p2-exec-activate | execution prompt | solid | | p2-dispatch | p2-exec-activate | execution prompt | solid |
| p2-exec-activate | p2-implement | | solid | | p2-exec-activate | p2-implement | | solid |
| p2-implement | p2-update-status | | solid | | p2-implement | p2-update-status | | solid |
@@ -95,23 +95,50 @@
--- ---
## PHASE 2.5: CODE REVIEW (Pre-Close)
### Nodes
| ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------|
| p25-start | /review | rounded-rect | user-lane | 24 |
| p25-reviewer-activate | Code Reviewer Activates | rectangle | reviewer-lane | 25 |
| p25-scan-changes | Scan Recent Changes | rectangle | reviewer-lane | 26 |
| p25-check-quality | Check Code Quality | rectangle | reviewer-lane | 27 |
| p25-security-scan | Security Scan | rectangle | reviewer-lane | 28 |
| p25-report | Generate Review Report | rectangle | reviewer-lane | 29 |
| p25-complete | Review Complete | rounded-rect | reviewer-lane | 30 |
### Edges
| From | To | Label | Style |
|------|----|-------|-------|
| p25-start | p25-reviewer-activate | invokes | solid |
| p25-reviewer-activate | p25-scan-changes | | solid |
| p25-scan-changes | p25-check-quality | | solid |
| p25-check-quality | p25-security-scan | | solid |
| p25-security-scan | p25-report | | solid |
| p25-report | p25-complete | | solid |
---
## PHASE 3: SPRINT CLOSE ## PHASE 3: SPRINT CLOSE
### Nodes ### Nodes
| ID | Label | Type | Lane | Sequence | | ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------| |----|-------|------|------|----------|
| p3-start | /sprint-close | rounded-rect | user-lane | 24 | | p3-start | /sprint-close | rounded-rect | user-lane | 31 |
| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 | | p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 32 |
| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 | | p3-review | Review Sprint | rectangle | orchestrator-lane | 33 |
| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 | | p3-gitea-status | Get Final Status | rectangle | gitea-lane | 34 |
| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 | | p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 35 |
| p3-user-input | Confirm Lessons | diamond | user-lane | 29 | | p3-user-input | Confirm Lessons | diamond | user-lane | 36 |
| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 | | p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 37 |
| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 | | p3-gitea-wiki-create | Store Lessons (Wiki) | rectangle | gitea-lane | 38 |
| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 | | p3-close-issues | Close Issues | rectangle | orchestrator-lane | 39 |
| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 | | p3-gitea-close | Mark Closed | rectangle | gitea-lane | 40 |
| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 | | p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 41 |
### Edges ### Edges
@@ -123,8 +150,8 @@
| p3-gitea-status | p3-capture | status data | dashed | | p3-gitea-status | p3-capture | status data | dashed |
| p3-capture | p3-user-input | proposed lessons | solid | | p3-capture | p3-user-input | proposed lessons | solid |
| p3-user-input | p3-create-wiki | confirmed | solid | | p3-user-input | p3-create-wiki | confirmed | solid |
| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid | | p3-create-wiki | p3-gitea-wiki-create | REST API (create_lesson) | solid |
| p3-wikijs-create | p3-close-issues | confirm | dashed | | p3-gitea-wiki-create | p3-close-issues | confirm | dashed |
| p3-close-issues | p3-gitea-close | REST API | solid | | p3-close-issues | p3-gitea-close | REST API | solid |
| p3-gitea-close | p3-complete | confirm | dashed | | p3-gitea-close | p3-complete | confirm | dashed |
@@ -133,59 +160,71 @@
## LAYOUT NOTES ## LAYOUT NOTES
``` ```
+--------+------------+---------------+------------+--------+----------+ +--------+------------+---------------+------------+----------+------------------+
| User | Planner | Orchestrator | Executor | Gitea | Wiki.js | | User | Planner | Orchestrator | Executor | Reviewer | Gitea |
+--------+------------+---------------+------------+--------+----------+ | | | | | | (Issues + Wiki) |
| | | | | | | +--------+------------+---------------+------------+----------+------------------+
| PHASE 1: SPRINT PLANNING | | | | | | | |
|---------------------------------------------------------------------+ | PHASE 1: SPRINT PLANNING |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +---->| O | | | | | | | | | | | | |
| | | | | | | | | +---->| O | | | | |
| | +----------|---------------|------------|------->| O | | | | | | | | |
| | |<---------|---------------|------------|--------+ | | | | +----------|---------------|------------|--------->| O (Wiki Query) |
| | | | | | | | | | |<---------|---------------|------------|----------+ | |
| | O<> | | | | | | | | | | | | |
| O<--->+ | | | | | | | | O<> | | | | |
| | | | | | | | | O<--->+ | | | | | |
| | +----------|---------------|----------->| O | | | | | | | | | |
| | O | | | | | | | +----------|---------------|------------|--------->| O (Issues) |
| | | | | | | | | O | | | | |
|---------------------------------------------------------------------+ | | | | | | |
| PHASE 2: SPRINT EXECUTION | |-------------------------------------------------------------------------------|
|---------------------------------------------------------------------+ | PHASE 2: SPRINT EXECUTION |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +-----|----------->| O | | | | | | | | | | | |
| | | | | | | | | +-----|----------->| O | | | |
| | | +-------------|----------->| O | | | | | | | | | |
| | | |<------------|------------+ | | | | | | +-------------|------------|--------->| O (Issues) |
| | | | | | | | | | | |<------------|------------|----------+ | |
| | | +------------>| O | | | | | | | | | | |
| | | | | | | | | | | +------------>| O | | |
| | | | +--------->| O | | | | | | | | | |
| | | | |<---------+ | | | | | | | +----------|--------->| O (Issues) |
| | | O<------------+ | | | | | | | | |<---------|----------+ | |
| | | | | | | | | | | O<------------+ | | | |
| | | O (loop) | | | | | | | | | | | |
| | | | | | | | | | O (loop) | | | |
|---------------------------------------------------------------------+ | | | | | | |
| PHASE 3: SPRINT CLOSE | |-------------------------------------------------------------------------------|
|---------------------------------------------------------------------+ | PHASE 2.5: CODE REVIEW |
| O | | | | | | |-------------------------------------------------------------------------------|
| | | | | | | | | O | | | | | |
| +-----|----------->| O | | | | | | | | | | | |
| | | +-------------|----------->| O | | | +-----|------------|---------------|----------->| O | |
| | | |<------------|------------+ | | | | | | | | | | |
| | | | | | | | | | | | | O->O->O | |
| O<----|-----------<+ | | | | | | | | | | | | |
| +-----|----------->| | | | | | | | | | | O | |
| | | +-------------|------------|------->| O | | | | | | | |
| | | |<------------|------------|--------+ | | |-------------------------------------------------------------------------------|
| | | +-------------|----------->| O | | | PHASE 3: SPRINT CLOSE |
| | | O | | | | |-------------------------------------------------------------------------------|
+--------+------------+---------------+------------+--------+----------+ | O | | | | | |
| | | | | | | |
| +-----|----------->| O | | | |
| | | +-------------|------------|--------->| O (Issues) |
| | | |<------------|------------|----------+ | |
| | | | | | | |
| O<----|-----------<+ | | | | |
| +-----|----------->| | | | | |
| | | +-------------|------------|--------->| O (Wiki Create) |
| | | |<------------|------------|----------+ | |
| | | +-------------|------------|--------->| O (Issues Close) |
| | | O | | | |
+--------+------------+---------------+------------+----------+------------------+
``` ```
--- ---
@@ -198,7 +237,8 @@
| Blue | #4A90D9 | Planner Agent | | Blue | #4A90D9 | Planner Agent |
| Green | #7CB342 | Orchestrator Agent | | Green | #7CB342 | Orchestrator Agent |
| Orange | #FF9800 | Executor Agent | | Orange | #FF9800 | Executor Agent |
| Gray | #9E9E9E | External Services | | Purple | #9C27B0 | Code Reviewer Agent |
| Gray | #9E9E9E | External Services (Gitea) |
--- ---
@@ -219,3 +259,13 @@
|-------|---------| |-------|---------|
| Solid | Action/Request | | Solid | Action/Request |
| Dashed | Response/Data return | | Dashed | Response/Data return |
---
## ARCHITECTURE NOTES
- **Gitea provides BOTH issue tracking AND wiki** (no separate wiki service)
- All wiki operations use Gitea REST API via MCP tools
- Lessons learned stored in Gitea Wiki under `lessons-learned/sprints/`
- MCP tools: `search_lessons`, `create_lesson`, `list_wiki_pages`, `get_wiki_page`
- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer

72
docs/architecture/component-map.spec.md
View File

@@ -13,22 +13,26 @@
| ID | Label | Type | Color | Position | | ID | Label | Type | Color | Position |
|----|-------|------|-------|----------| |----|-------|------|-------|----------|
| projman | projman | rectangle | #4A90D9 | top-center | | projman | projman | rectangle | #4A90D9 | top-center |
| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right | | projman-pmo | projman-pmo (planned) | rectangle | #4A90D9 | top-right |
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left | | project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
| claude-config | claude-config-maintainer | rectangle | #4A90D9 | bottom-left |
| cmdb-assistant | cmdb-assistant | rectangle | #4A90D9 | bottom-right |
### MCP Servers (Green - #7CB342) ### MCP Servers (Green - #7CB342)
| ID | Label | Type | Color | Position | MCP servers are **bundled inside each plugin** that needs them.
|----|-------|------|-------|----------|
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | | ID | Label | Type | Color | Position | Bundled In |
| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right | |----|-------|------|-------|----------|------------|
| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | projman |
| netbox-mcp | NetBox MCP Server | rectangle | #7CB342 | middle-right | cmdb-assistant |
### External Systems (Gray - #9E9E9E) ### External Systems (Gray - #9E9E9E)
| ID | Label | Type | Color | Position | | ID | Label | Type | Color | Position |
|----|-------|------|-------|----------| |----|-------|------|-------|----------|
| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left | | gitea-instance | Gitea\n(Issues + Wiki) | cylinder | #9E9E9E | bottom-left |
| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right | | netbox-instance | NetBox | cylinder | #9E9E9E | bottom-right |
### Configuration (Orange - #FF9800) ### Configuration (Orange - #FF9800)
@@ -45,10 +49,8 @@
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| projman | gitea-mcp | uses | solid | forward | | projman | gitea-mcp | bundled | solid | bidirectional |
| projman | wikijs-mcp | uses | solid | forward | | cmdb-assistant | netbox-mcp | bundled | solid | bidirectional |
| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward |
| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward |
### Plugin Dependencies ### Plugin Dependencies
@@ -61,16 +63,16 @@
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| gitea-mcp | gitea-instance | REST API | solid | forward | | gitea-mcp | gitea-instance | REST API | solid | forward |
| wikijs-mcp | wikijs-instance | GraphQL | solid | forward | | netbox-mcp | netbox-instance | REST API | solid | forward |
### Configuration Connections ### Configuration Connections
| From | To | Label | Style | Arrow | | From | To | Label | Style | Arrow |
|------|----|-------|-------|-------| |------|----|-------|-------|-------|
| system-config | gitea-mcp | credentials | dashed | forward | | system-config | gitea-mcp | credentials | dashed | forward |
| system-config | wikijs-mcp | credentials | dashed | forward | | system-config | netbox-mcp | credentials | dashed | forward |
| project-config | gitea-mcp | repo context | dashed | forward | | project-config | gitea-mcp | repo context | dashed | forward |
| project-config | wikijs-mcp | project path | dashed | forward | | project-config | netbox-mcp | site context | dashed | forward |
--- ---
@@ -78,9 +80,8 @@
| ID | Label | Contains | Style | | ID | Label | Contains | Style |
|----|-------|----------|-------| |----|-------|----------|-------|
| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border | | plugins-group | Plugins | projman, projman-pmo, project-hygiene, claude-config, cmdb-assistant | light blue border |
| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border | | external-group | External Services | gitea-instance, netbox-instance | light gray border |
| external-group | External Services | gitea-instance, wikijs-instance | light gray border |
| config-group | Configuration | system-config, project-config | light orange border | | config-group | Configuration | system-config, project-config | light orange border |
--- ---
@@ -92,25 +93,21 @@
| PLUGINS GROUP | | PLUGINS GROUP |
| +----------------+ +----------------+ +-------------------+ | | +----------------+ +----------------+ +-------------------+ |
| | project- | | projman | | projman-pmo | | | | project- | | projman | | projman-pmo | |
| | hygiene | | | | | | | | hygiene | | [gitea-mcp] | | (planned) | |
| +----------------+ +-------+--------+ +--------+----------+ | | +----------------+ +-------+--------+ +-------------------+ |
| | | | | | |
| +----------------+ +-------------------+ |
| | claude-config | | cmdb-assistant | |
| | -maintainer | | [netbox-mcp] | |
| +----------------+ +--------+----------+ |
+------------------------------------------------------------------+ +------------------------------------------------------------------+
| | |
v v v
+------------------------------------------------------------------+
| MCP SERVERS GROUP |
| +-------------------+ +-------------------+ |
| | Gitea MCP Server | | Wiki.js MCP Server| |
| +--------+----------+ +---------+---------+ |
+------------------------------------------------------------------+
| |
v v
+------------------------------------------------------------------+ +------------------------------------------------------------------+
| EXTERNAL SERVICES GROUP | | EXTERNAL SERVICES GROUP |
| +-------------------+ +-------------------+ | | +-------------------+ +-------------------+ |
| | Gitea | | Wiki.js | | | | Gitea | | NetBox | |
| | gitea.hotserv.cloud | wikijs.hotserv.cloud | | | (Issues + Wiki) | | | |
| +-------------------+ +-------------------+ | | +-------------------+ +-------------------+ |
+------------------------------------------------------------------+ +------------------------------------------------------------------+
@@ -128,6 +125,15 @@ CONFIG GROUP (left side): CONFIG GROUP (right side):
| Color | Hex | Meaning | | Color | Hex | Meaning |
|-------|-----|---------| |-------|-----|---------|
| Blue | #4A90D9 | Plugins | | Blue | #4A90D9 | Plugins |
| Green | #7CB342 | MCP Servers | | Green | #7CB342 | MCP Servers (bundled in plugins) |
| Gray | #9E9E9E | External Systems | | Gray | #9E9E9E | External Systems |
| Orange | #FF9800 | Configuration | | Orange | #FF9800 | Configuration |
---
## ARCHITECTURE NOTES
- MCP servers are **bundled inside plugins** (not shared at root)
- Gitea provides both issue tracking AND wiki (lessons learned)
- No separate Wiki.js - all wiki functionality uses Gitea Wiki
- Each plugin is self-contained for Claude Code caching