From 14425cfad16d3dd35a20f503cbad0a14161585d7 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Tue, 20 Jan 2026 11:22:20 -0500 Subject: [PATCH] fix: remove Wiki.js references from architecture docs - 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 --- docs/architecture/agent-workflow.spec.md | 200 ++++++++++++++--------- docs/architecture/component-map.spec.md | 72 ++++---- 2 files changed, 164 insertions(+), 108 deletions(-) diff --git a/docs/architecture/agent-workflow.spec.md b/docs/architecture/agent-workflow.spec.md index f43c7a7..a1db283 100644 --- a/docs/architecture/agent-workflow.spec.md +++ b/docs/architecture/agent-workflow.spec.md @@ -2,7 +2,7 @@ **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 @@ -16,8 +16,8 @@ | planner-lane | Planner Agent | #4A90D9 | 2 | | orchestrator-lane | Orchestrator Agent | #7CB342 | 3 | | executor-lane | Executor Agent | #FF9800 | 4 | -| gitea-lane | Gitea | #9E9E9E | 5 | -| wikijs-lane | Wiki.js | #9E9E9E | 6 (rightmost) | +| reviewer-lane | Code Reviewer Agent | #9C27B0 | 5 | +| gitea-lane | Gitea (Issues + Wiki) | #9E9E9E | 6 (rightmost) | --- @@ -30,7 +30,7 @@ | p1-start | /sprint-plan | rounded-rect | user-lane | 1 | | p1-activate | Planner Activates | rectangle | planner-lane | 2 | | 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-clarify | Ask Clarifying Questions | diamond | planner-lane | 6 | | p1-user-answers | Provide Answers | rectangle | user-lane | 7 | @@ -44,8 +44,8 @@ |------|----|-------|-------| | p1-start | p1-activate | invokes | solid | | p1-activate | p1-search-lessons | | solid | -| p1-search-lessons | p1-wikijs-query | GraphQL search | solid | -| p1-wikijs-query | p1-return-lessons | lessons data | dashed | +| p1-search-lessons | p1-gitea-wiki-query | REST API (search_lessons) | solid | +| p1-gitea-wiki-query | p1-return-lessons | lessons data | dashed | | p1-return-lessons | p1-clarify | | solid | | p1-clarify | p1-user-answers | questions | solid | | p1-user-answers | p1-clarify | answers | dashed | @@ -65,7 +65,7 @@ | p2-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 12 | | p2-fetch-issues | Fetch Sprint Issues | rectangle | orchestrator-lane | 13 | | 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-exec-activate | Executor Activates | rectangle | executor-lane | 17 | | p2-implement | Implement Task | rectangle | executor-lane | 18 | @@ -83,7 +83,7 @@ | p2-orch-activate | p2-fetch-issues | | solid | | p2-fetch-issues | p2-gitea-list | REST API | solid | | 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-exec-activate | p2-implement | | 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 ### Nodes | ID | Label | Type | Lane | Sequence | |----|-------|------|------|----------| -| p3-start | /sprint-close | rounded-rect | user-lane | 24 | -| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 25 | -| p3-review | Review Sprint | rectangle | orchestrator-lane | 26 | -| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 27 | -| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 28 | -| p3-user-input | Confirm Lessons | diamond | user-lane | 29 | -| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 30 | -| p3-wikijs-create | Store Lessons | rectangle | wikijs-lane | 31 | -| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 32 | -| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 33 | -| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 34 | +| p3-start | /sprint-close | rounded-rect | user-lane | 31 | +| p3-orch-activate | Orchestrator Activates | rectangle | orchestrator-lane | 32 | +| p3-review | Review Sprint | rectangle | orchestrator-lane | 33 | +| p3-gitea-status | Get Final Status | rectangle | gitea-lane | 34 | +| p3-capture | Capture Lessons Learned | rectangle | orchestrator-lane | 35 | +| p3-user-input | Confirm Lessons | diamond | user-lane | 36 | +| p3-create-wiki | Create Wiki Pages | rectangle | orchestrator-lane | 37 | +| p3-gitea-wiki-create | Store Lessons (Wiki) | rectangle | gitea-lane | 38 | +| p3-close-issues | Close Issues | rectangle | orchestrator-lane | 39 | +| p3-gitea-close | Mark Closed | rectangle | gitea-lane | 40 | +| p3-complete | Sprint Closed | rounded-rect | orchestrator-lane | 41 | ### Edges @@ -123,8 +150,8 @@ | p3-gitea-status | p3-capture | status data | dashed | | p3-capture | p3-user-input | proposed lessons | solid | | p3-user-input | p3-create-wiki | confirmed | solid | -| p3-create-wiki | p3-wikijs-create | GraphQL mutation | solid | -| p3-wikijs-create | p3-close-issues | confirm | dashed | +| p3-create-wiki | p3-gitea-wiki-create | REST API (create_lesson) | solid | +| p3-gitea-wiki-create | p3-close-issues | confirm | dashed | | p3-close-issues | p3-gitea-close | REST API | solid | | p3-gitea-close | p3-complete | confirm | dashed | @@ -133,59 +160,71 @@ ## LAYOUT NOTES ``` -+--------+------------+---------------+------------+--------+----------+ -| User | Planner | Orchestrator | Executor | Gitea | Wiki.js | -+--------+------------+---------------+------------+--------+----------+ -| | | | | | | -| PHASE 1: SPRINT PLANNING | -|---------------------------------------------------------------------+ -| O | | | | | | -| | | | | | | | -| +---->| O | | | | | -| | | | | | | | -| | +----------|---------------|------------|------->| O | -| | |<---------|---------------|------------|--------+ | | -| | | | | | | | -| | O<> | | | | | -| O<--->+ | | | | | | -| | | | | | | | -| | +----------|---------------|----------->| O | | -| | O | | | | | -| | | | | | | -|---------------------------------------------------------------------+ -| PHASE 2: SPRINT EXECUTION | -|---------------------------------------------------------------------+ -| O | | | | | | -| | | | | | | | -| +-----|----------->| O | | | | -| | | | | | | | -| | | +-------------|----------->| O | | -| | | |<------------|------------+ | | | -| | | | | | | | -| | | +------------>| O | | | -| | | | | | | | -| | | | +--------->| O | | -| | | | |<---------+ | | | -| | | O<------------+ | | | | -| | | | | | | | -| | | O (loop) | | | | -| | | | | | | -|---------------------------------------------------------------------+ -| PHASE 3: SPRINT CLOSE | -|---------------------------------------------------------------------+ -| O | | | | | | -| | | | | | | | -| +-----|----------->| O | | | | -| | | +-------------|----------->| O | | -| | | |<------------|------------+ | | | -| | | | | | | | -| O<----|-----------<+ | | | | | -| +-----|----------->| | | | | | -| | | +-------------|------------|------->| O | -| | | |<------------|------------|--------+ | | -| | | +-------------|----------->| O | | -| | | O | | | | -+--------+------------+---------------+------------+--------+----------+ ++--------+------------+---------------+------------+----------+------------------+ +| User | Planner | Orchestrator | Executor | Reviewer | Gitea | +| | | | | | (Issues + Wiki) | ++--------+------------+---------------+------------+----------+------------------+ +| | | | | | | +| PHASE 1: SPRINT PLANNING | +|-------------------------------------------------------------------------------| +| O | | | | | | +| | | | | | | | +| +---->| O | | | | | +| | | | | | | | +| | +----------|---------------|------------|--------->| O (Wiki Query) | +| | |<---------|---------------|------------|----------+ | | +| | | | | | | | +| | O<> | | | | | +| O<--->+ | | | | | | +| | | | | | | | +| | +----------|---------------|------------|--------->| O (Issues) | +| | O | | | | | +| | | | | | | +|-------------------------------------------------------------------------------| +| PHASE 2: SPRINT EXECUTION | +|-------------------------------------------------------------------------------| +| O | | | | | | +| | | | | | | | +| +-----|----------->| O | | | | +| | | | | | | | +| | | +-------------|------------|--------->| O (Issues) | +| | | |<------------|------------|----------+ | | +| | | | | | | | +| | | +------------>| O | | | +| | | | | | | | +| | | | +----------|--------->| O (Issues) | +| | | | |<---------|----------+ | | +| | | O<------------+ | | | | +| | | | | | | | +| | | O (loop) | | | | +| | | | | | | +|-------------------------------------------------------------------------------| +| PHASE 2.5: CODE REVIEW | +|-------------------------------------------------------------------------------| +| O | | | | | | +| | | | | | | | +| +-----|------------|---------------|----------->| O | | +| | | | | | | | +| | | | | O->O->O | | +| | | | | | | | +| | | | | O | | +| | | | | | | +|-------------------------------------------------------------------------------| +| PHASE 3: SPRINT CLOSE | +|-------------------------------------------------------------------------------| +| O | | | | | | +| | | | | | | | +| +-----|----------->| O | | | | +| | | +-------------|------------|--------->| O (Issues) | +| | | |<------------|------------|----------+ | | +| | | | | | | | +| O<----|-----------<+ | | | | | +| +-----|----------->| | | | | | +| | | +-------------|------------|--------->| O (Wiki Create) | +| | | |<------------|------------|----------+ | | +| | | +-------------|------------|--------->| O (Issues Close) | +| | | O | | | | ++--------+------------+---------------+------------+----------+------------------+ ``` --- @@ -198,7 +237,8 @@ | Blue | #4A90D9 | Planner Agent | | Green | #7CB342 | Orchestrator 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 | | 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 diff --git a/docs/architecture/component-map.spec.md b/docs/architecture/component-map.spec.md index 5ef3845..5784578 100644 --- a/docs/architecture/component-map.spec.md +++ b/docs/architecture/component-map.spec.md @@ -13,22 +13,26 @@ | ID | Label | Type | Color | Position | |----|-------|------|-------|----------| | 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 | +| claude-config | claude-config-maintainer | rectangle | #4A90D9 | bottom-left | +| cmdb-assistant | cmdb-assistant | rectangle | #4A90D9 | bottom-right | ### MCP Servers (Green - #7CB342) -| ID | Label | Type | Color | Position | -|----|-------|------|-------|----------| -| gitea-mcp | Gitea MCP Server | rectangle | #7CB342 | middle-left | -| wikijs-mcp | Wiki.js MCP Server | rectangle | #7CB342 | middle-right | +MCP servers are **bundled inside each plugin** that needs them. + +| ID | Label | Type | Color | Position | Bundled In | +|----|-------|------|-------|----------|------------| +| 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) | ID | Label | Type | Color | Position | |----|-------|------|-------|----------| -| gitea-instance | Gitea\ngitea.hotserv.cloud | cylinder | #9E9E9E | bottom-left | -| wikijs-instance | Wiki.js\nwikijs.hotserv.cloud | cylinder | #9E9E9E | bottom-right | +| gitea-instance | Gitea\n(Issues + Wiki) | cylinder | #9E9E9E | bottom-left | +| netbox-instance | NetBox | cylinder | #9E9E9E | bottom-right | ### Configuration (Orange - #FF9800) @@ -45,10 +49,8 @@ | From | To | Label | Style | Arrow | |------|----|-------|-------|-------| -| projman | gitea-mcp | uses | solid | forward | -| projman | wikijs-mcp | uses | solid | forward | -| projman-pmo | gitea-mcp | uses (company-wide) | solid | forward | -| projman-pmo | wikijs-mcp | uses (company-wide) | solid | forward | +| projman | gitea-mcp | bundled | solid | bidirectional | +| cmdb-assistant | netbox-mcp | bundled | solid | bidirectional | ### Plugin Dependencies @@ -61,16 +63,16 @@ | From | To | Label | Style | Arrow | |------|----|-------|-------|-------| | 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 | From | To | Label | Style | Arrow | |------|----|-------|-------|-------| | 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 | wikijs-mcp | project path | dashed | forward | +| project-config | netbox-mcp | site context | dashed | forward | --- @@ -78,9 +80,8 @@ | ID | Label | Contains | Style | |----|-------|----------|-------| -| plugins-group | Plugins | projman, projman-pmo, project-hygiene | light blue border | -| mcp-group | Shared MCP Servers | gitea-mcp, wikijs-mcp | light green border | -| external-group | External Services | gitea-instance, wikijs-instance | light gray border | +| plugins-group | Plugins | projman, projman-pmo, project-hygiene, claude-config, cmdb-assistant | light blue border | +| external-group | External Services | gitea-instance, netbox-instance | light gray border | | config-group | Configuration | system-config, project-config | light orange border | --- @@ -92,25 +93,21 @@ | PLUGINS GROUP | | +----------------+ +----------------+ +-------------------+ | | | project- | | projman | | projman-pmo | | -| | hygiene | | | | | | -| +----------------+ +-------+--------+ +--------+----------+ | -| | | | +| | hygiene | | [gitea-mcp] | | (planned) | | +| +----------------+ +-------+--------+ +-------------------+ | +| | | +| +----------------+ +-------------------+ | +| | claude-config | | cmdb-assistant | | +| | -maintainer | | [netbox-mcp] | | +| +----------------+ +--------+----------+ | +------------------------------------------------------------------+ - | | - v v -+------------------------------------------------------------------+ -| MCP SERVERS GROUP | -| +-------------------+ +-------------------+ | -| | Gitea MCP Server | | Wiki.js MCP Server| | -| +--------+----------+ +---------+---------+ | -+------------------------------------------------------------------+ - | | - v v + | + v +------------------------------------------------------------------+ | EXTERNAL SERVICES GROUP | | +-------------------+ +-------------------+ | -| | Gitea | | Wiki.js | | -| | gitea.hotserv.cloud | wikijs.hotserv.cloud | +| | Gitea | | NetBox | | +| | (Issues + Wiki) | | | | | +-------------------+ +-------------------+ | +------------------------------------------------------------------+ @@ -128,6 +125,15 @@ CONFIG GROUP (left side): CONFIG GROUP (right side): | Color | Hex | Meaning | |-------|-----|---------| | Blue | #4A90D9 | Plugins | -| Green | #7CB342 | MCP Servers | +| Green | #7CB342 | MCP Servers (bundled in plugins) | | Gray | #9E9E9E | External Systems | | 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