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

feat: project refactoring - folder cleanup, governance, and automation

Browse Source 
Project Structure Cleanup:
- Remove deprecated cmdb-assistant plugin
- Remove development output files (test scripts, status reports)
- Remove IDE-specific workspace files
- Create scripts/ directory for automation
- Create docs/architecture/ for Draw.io diagrams
- Create docs/workflows/ for workflow documentation
- Create .scratch/ directory for transient work

Governance & Documentation:
- Add File Creation Governance section to CLAUDE.md
- Add architecture diagram specifications (component-map, agent-workflow)
- Add docs/UPDATING.md with update workflow
- Update CHANGELOG.md with all changes

Installation Automation:
- Add scripts/setup.sh for initial installation
- Add scripts/post-update.sh for updates after git pull
- Add /initial-setup slash command

Maintenance:
- Update .gitignore with scratch directory
- Fix all project name references (use support-claude-mktplace)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2025-12-11 22:17:27 -05:00
parent b6a77d9b35
commit 8bb69d3556
29 changed files with 930 additions and 3315 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
docs/architecture/agent-workflow.spec.md Normal file
View File

@@ -0,0 +1,221 @@
# Agent Workflow - Draw.io Specification
**Target File:** `docs/architecture/agent-workflow.drawio`
**Purpose:** Shows when Planner, Orchestrator, and Executor agents trigger during sprint lifecycle.
**Diagram Type:** Swimlane / Sequence Diagram
---
## SWIMLANES
| ID | Label | Color | Position |
|----|-------|-------|----------|
| user-lane | User | #E3F2FD | 1 (leftmost) |
| 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) |
---
## PHASE 1: SPRINT PLANNING
### Nodes
| ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------|
| 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-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 |
| p1-create-issues | Create Issues with Labels | rectangle | planner-lane | 8 |
| p1-gitea-create | Store Issues | rectangle | gitea-lane | 9 |
| p1-plan-complete | Planning Complete | rounded-rect | planner-lane | 10 |
### Edges
| From | To | Label | Style |
|------|----|-------|-------|
| 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-return-lessons | p1-clarify | | solid |
| p1-clarify | p1-user-answers | questions | solid |
| p1-user-answers | p1-clarify | answers | dashed |
| p1-clarify | p1-create-issues | | solid |
| p1-create-issues | p1-gitea-create | REST API | solid |
| p1-gitea-create | p1-plan-complete | confirm | dashed |
---
## PHASE 2: SPRINT EXECUTION
### Nodes
| ID | Label | Type | Lane | Sequence |
|----|-------|------|------|----------|
| p2-start | /sprint-start | rounded-rect | user-lane | 11 |
| 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-dispatch | Dispatch Task | rectangle | orchestrator-lane | 16 |
| p2-exec-activate | Executor Activates | rectangle | executor-lane | 17 |
| p2-implement | Implement Task | rectangle | executor-lane | 18 |
| p2-update-status | Update Issue Status | rectangle | executor-lane | 19 |
| p2-gitea-update | Update Issue | rectangle | gitea-lane | 20 |
| p2-report | Report Completion | rectangle | executor-lane | 21 |
| p2-loop | More Tasks? | diamond | orchestrator-lane | 22 |
| p2-exec-complete | Execution Complete | rounded-rect | orchestrator-lane | 23 |
### Edges
| From | To | Label | Style |
|------|----|-------|-------|
| p2-start | p2-orch-activate | invokes | solid |
| 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-dispatch | p2-exec-activate | execution prompt | solid |
| p2-exec-activate | p2-implement | | solid |
| p2-implement | p2-update-status | | solid |
| p2-update-status | p2-gitea-update | REST API | solid |
| p2-gitea-update | p2-report | confirm | dashed |
| p2-report | p2-loop | | solid |
| p2-loop | p2-dispatch | yes | solid |
| p2-loop | p2-exec-complete | no | 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 |
### Edges
| From | To | Label | Style |
|------|----|-------|-------|
| p3-start | p3-orch-activate | invokes | solid |
| p3-orch-activate | p3-review | | solid |
| p3-review | p3-gitea-status | REST API | solid |
| 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-close-issues | p3-gitea-close | REST API | solid |
| p3-gitea-close | p3-complete | confirm | dashed |
---
## 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 | | | |
+--------+------------+---------------+------------+--------+----------+
```
---
## COLOR LEGEND
| Color | Hex | Meaning |
|-------|-----|---------|
| Light Blue | #E3F2FD | User actions |
| Blue | #4A90D9 | Planner Agent |
| Green | #7CB342 | Orchestrator Agent |
| Orange | #FF9800 | Executor Agent |
| Gray | #9E9E9E | External Services |
---
## SHAPE LEGEND
| Shape | Meaning |
|-------|---------|
| Rounded Rectangle | Start/End points (commands) |
| Rectangle | Process/Action |
| Diamond | Decision point |
| Cylinder | Data store (in component map) |
---
## ARROW LEGEND
| Style | Meaning |
|-------|---------|
| Solid | Action/Request |
| Dashed | Response/Data return |

133
docs/architecture/component-map.spec.md Normal file
View File

@@ -0,0 +1,133 @@
# Component Map - Draw.io Specification
**Target File:** `docs/architecture/component-map.drawio`
**Purpose:** Shows all plugins, MCP servers, hooks and their relationships.
---
## NODES
### Plugins (Blue - #4A90D9)
| ID | Label | Type | Color | Position |
|----|-------|------|-------|----------|
| projman | projman | rectangle | #4A90D9 | top-center |
| projman-pmo | projman-pmo | rectangle | #4A90D9 | top-right |
| project-hygiene | project-hygiene | rectangle | #4A90D9 | top-left |
### 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 |
### 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 |
### Configuration (Orange - #FF9800)
| ID | Label | Type | Color | Position |
|----|-------|------|-------|----------|
| system-config | System Config\n~/.config/claude/ | rectangle | #FF9800 | far-left |
| project-config | Project Config\n.env | rectangle | #FF9800 | far-right |
---
## EDGES
### Plugin to MCP Server Connections
| 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 |
### Plugin Dependencies
| From | To | Label | Style | Arrow |
|------|----|-------|-------|-------|
| projman-pmo | projman | depends on | dashed | forward |
### MCP Server to External System Connections
| From | To | Label | Style | Arrow |
|------|----|-------|-------|-------|
| gitea-mcp | gitea-instance | REST API | solid | forward |
| wikijs-mcp | wikijs-instance | GraphQL | solid | forward |
### Configuration Connections
| From | To | Label | Style | Arrow |
|------|----|-------|-------|-------|
| system-config | gitea-mcp | credentials | dashed | forward |
| system-config | wikijs-mcp | credentials | dashed | forward |
| project-config | gitea-mcp | repo context | dashed | forward |
| project-config | wikijs-mcp | project path | dashed | forward |
---
## GROUPS
| 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 |
| config-group | Configuration | system-config, project-config | light orange border |
---
## LAYOUT NOTES
```
+------------------------------------------------------------------+
| PLUGINS GROUP |
| +----------------+ +----------------+ +-------------------+ |
| | project- | | projman | | projman-pmo | |
| | hygiene | | | | | |
| +----------------+ +-------+--------+ +--------+----------+ |
| | | |
+------------------------------------------------------------------+
| |
v v
+------------------------------------------------------------------+
| MCP SERVERS GROUP |
| +-------------------+ +-------------------+ |
| | Gitea MCP Server | | Wiki.js MCP Server| |
| +--------+----------+ +---------+---------+ |
+------------------------------------------------------------------+
| |
v v
+------------------------------------------------------------------+
| EXTERNAL SERVICES GROUP |
| +-------------------+ +-------------------+ |
| | Gitea | | Wiki.js | |
| | gitea.hotserv.cloud | wikijs.hotserv.cloud |
| +-------------------+ +-------------------+ |
+------------------------------------------------------------------+
CONFIG GROUP (left side): CONFIG GROUP (right side):
+-------------------+ +-------------------+
| System Config | | Project Config |
| ~/.config/claude/ | | .env |
+-------------------+ +-------------------+
```
---
## COLOR LEGEND
| Color | Hex | Meaning |
|-------|-----|---------|
| Blue | #4A90D9 | Plugins |
| Green | #7CB342 | MCP Servers |
| Gray | #9E9E9E | External Systems |
| Orange | #FF9800 | Configuration |