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

Add "Change V04.1.0: Proposal"

Leo Miranda
2026-01-26 14:52:15 +00:00
parent 49dcadf835
commit 870e75ba4a
1 changed files with 273 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
Change-V04.1.0%3A-Proposal.md Normal file

@@ -0,0 +1,273 @@
> **Type:** Change Proposal
> **Version:** V04.1.0
> **Plugin:** projman
> **Status:** In Progress
> **Date:** 2026-01-25
---
# Wiki-Based Planning Workflow Enhancement
## Problem Statement
Currently, projman's sprint planning workflow has these limitations:
1. **Confusion between planning docs and documentation** - Planning documents in `docs/changes/` can be confused with regular project documentation
2. **Lost planning context** - Once issues are created, the original planning rationale may be lost or disconnected
3. **No iteration tracking** - When a feature requires multiple attempts, there's no structured way to track each implementation
4. **Fragmented audit trail** - The path from idea → planning → implementation → lessons is not clearly linked
## Proposed Solution
Integrate wiki-based change proposals into the projman workflow, creating a structured system for tracking planning documents separately from regular documentation.
### Wiki Structure
```
wiki/
├── lessons-learned/
│ └── sprints/ # Existing
│ ├── sprint-17.md
│ └── sprint-18.md
└── changes/ # NEW
└── v04.0.0/
├── proposal.md
└── implementation-1.md
└── v04.1.0/
├── proposal.md
└── implementation-1.md
```
### Page Naming Convention
| Type | Pattern | Example |
|------|---------|---------|
| Proposal | `Change VXX.X.X: Proposal` | Change V04.0.0: Proposal |
| Implementation | `Change VXX.X.X: Proposal (Implementation N)` | Change V04.1.0: Proposal (Implementation 1) |
| Internal Work | `Change Sprint-NN: Proposal` | Change Sprint-17: Proposal |
### Tagging System
**For Proposals:**
```markdown
> **Type:** Change Proposal
> **Version:** VXX.X.X
> **Plugin:** plugin-name (optional)
> **Status:** Pending | In Progress | Implemented | Abandoned
> **Date:** YYYY-MM-DD
## Implementations
- [Implementation 1](link) - description
```
**For Implementations:**
```markdown
> **Type:** Change Proposal Implementation
> **Version:** VXX.X.X
> **Status:** In Progress | Implemented | Failed
> **Date:** YYYY-MM-DD
> **Origin:** [Proposal Link](link)
> **Sprint:** Sprint XX (optional)
```
## Input Document Format
Standardized frontmatter for local input files (`docs/changes/*.md`):
```yaml
---
version: "4.1.0" # or "sprint-17" for internal work
title: "Wiki-Based Planning Workflow"
plugin: projman # optional, for plugin-specific changes
type: feature # feature | bugfix | refactor | infra
---
# Feature Description
[Free-form content describing what you want to build...]
```
## Flexible Input Sources
| Source | Description | What `/sprint-plan` does |
|--------|-------------|--------------------------|
| **Local file** | `docs/changes/v4.1.0-feature.md` | Parse, migrate to wiki, delete local |
| **Conversation** | Discussion with Claude leads to plan | Create wiki pages from conversation context |
| **Existing wiki** | User already created wiki proposal | Skip creation, proceed to implementation page |
### Input Detection Logic
```
IF docs/changes/*.md exists:
→ Use local file (migrate to wiki, then delete)
ELSE IF wiki "Change VXX.X.X: Proposal" exists:
→ Use existing wiki (add new implementation)
ELSE IF conversation contains planning context:
→ Ask user to confirm version/title
→ Create proposal from conversation
ELSE:
→ Ask user: "What are we planning?"
```
## Enhanced Workflow
### /sprint-plan (Enhanced)
```
┌─────────────────────────────────────────────────────────────────┐
│ 1. VALIDATION (existing) │
│ - Check branch (development) │
│ - Validate repo/org configuration │
│ - Sync labels if needed │
├─────────────────────────────────────────────────────────────────┤
│ 2. DETERMINE INPUT SOURCE (new) │
│ - Check for docs/changes/*.md files │
│ - Check for existing wiki proposal (by version) │
│ - If neither: use current conversation context │
│ │
│ ASK USER if ambiguous: │
│ "I found [X]. Should I use this as the planning input?" │
├─────────────────────────────────────────────────────────────────┤
│ 3. SEARCH LESSONS LEARNED (existing) │
│ - Query wiki for relevant past lessons │
│ - Surface applicable patterns/warnings │
├─────────────────────────────────────────────────────────────────┤
│ 4. CREATE/UPDATE WIKI PROPOSAL (conditional) │
│ - IF local file: migrate content, delete file │
│ - IF conversation: create from discussion │
│ - IF existing wiki: skip, use as-is │
├─────────────────────────────────────────────────────────────────┤
│ 5. CREATE WIKI IMPLEMENTATION PAGE (new) │
│ - Determine implementation number (N) │
│ - Create "Change V04.1.0: Proposal (Implementation N)" │
│ - Content: migrated from input document │
│ - Tags: Type, Version, Status=In Progress, Date, Origin │
│ - Update proposal page with link to this implementation │
├─────────────────────────────────────────────────────────────────┤
│ 6. ARCHITECTURE ANALYSIS (existing) │
│ - Analyze codebase │
│ - Ask clarifying questions │
│ - Identify affected files │
├─────────────────────────────────────────────────────────────────┤
│ 7. CREATE GITEA ISSUES (existing, enhanced) │
│ - Create issues for each task │
│ - ADD: wiki implementation reference in description │
│ "Implementation: [Change V04.1.0 (Impl 1)](wiki-link)" │
├─────────────────────────────────────────────────────────────────┤
│ 8. CLEANUP (new) │
│ - Delete local input file (docs/changes/v4.1.0-*.md) │
│ - Wiki is now single source of truth │
└─────────────────────────────────────────────────────────────────┘
```
### /sprint-close (Enhanced)
```
┌─────────────────────────────────────────────────────────────────┐
│ 1. VERIFY ISSUES CLOSED (existing) │
│ - Check all milestone issues are closed │
│ - Warn if any remain open │
├─────────────────────────────────────────────────────────────────┤
│ 2. CAPTURE LESSONS LEARNED (existing, enhanced) │
│ - Gather lessons from sprint │
│ - Create wiki page: lessons/sprints/sprint-XX.md │
│ - ADD: link to implementation page in lesson metadata │
├─────────────────────────────────────────────────────────────────┤
│ 3. UPDATE WIKI IMPLEMENTATION PAGE (new) │
│ - Set Status: Implemented (or Failed) │
│ - Add link to lessons learned page │
│ - Add completion date │
├─────────────────────────────────────────────────────────────────┤
│ 4. UPDATE WIKI PROPOSAL PAGE (new) │
│ - Update implementation entry status │
│ - If ALL implementations complete: │
│ Set proposal Status: Implemented │
└─────────────────────────────────────────────────────────────────┘
```
## Traceability Chain
```
Input (local file / conversation / existing wiki)
│
▼ [migrated by /sprint-plan]
Wiki: "Change V04.1.0: Proposal" (persistent)
│
▼ [created by /sprint-plan]
Wiki: "Change V04.1.0: Proposal (Implementation 1)" (versioned)
│
▼ [referenced in description]
Gitea Issues (#42, #43, #44)
│
▼ [referenced in commits]
Git Commits (feat: add wiki workflow, closes #42)
│
▼ [captured by /sprint-close]
Wiki: "lessons/sprints/v4.1.0-implementation-1" (linked back)
```
## Benefits
| Benefit | Description |
|---------|-------------|
| **Separation of Concerns** | Planning docs clearly distinct from project documentation |
| **Full Traceability** | Clear path from idea to lessons learned |
| **Iteration Support** | Multiple implementations per proposal |
| **Single Source of Truth** | Wiki is authoritative, local files are temporary |
| **Historical Record** | Easy to review what was planned vs implemented |
| **Cross-Version Learning** | Lessons linked to specific implementations |
| **Flexible Input** | Start from file, conversation, or existing wiki |
## Implementation Phases
| Phase | Scope | Effort |
|-------|-------|--------|
| **Phase 1** | Add wiki proposal/implementation creation to `/sprint-plan` | M |
| **Phase 2** | Add wiki status updates to `/sprint-close` | S |
| **Phase 3** | Add cross-linking (issues ↔ wiki, lessons ↔ implementation) | M |
| **Phase 4** | Add `/proposal-status` command for viewing proposal tree | S |
## MCP Tools Required
All tools already exist in the Gitea MCP server:
- `list_wiki_pages` - Check existing proposals
- `get_wiki_page` - Read proposal/implementation content
- `create_wiki_page` - Create new proposal/implementation
- `update_wiki_page` - Update status, add links
## Affected Files
| File | Changes |
|------|---------|
| `plugins/projman/commands/sprint-plan.md` | Add wiki workflow steps |
| `plugins/projman/commands/sprint-close.md` | Add wiki status updates |
| `plugins/projman/agents/planner.md` | Include wiki workflow in planning |
| `plugins/projman/agents/orchestrator.md` | Include wiki updates in close |
| `plugins/projman/README.md` | Document wiki workflow |
## Resolved Questions
| Question | Decision |
|----------|----------|
| **Version vs Sprint numbering** | **Hybrid** - `Change VXX.X.X:` for releases, `Change Sprint-NN:` for internal work |
| **Multi-feature sprints** | **One proposal per feature** - each feature gets its own proposal page |
| **Input document format** | **Standardized frontmatter** - version, title, plugin (optional), type |
## Success Criteria
- [ ] Sprint planning creates wiki proposal and implementation pages
- [ ] Sprint close updates wiki statuses
- [ ] Issues reference wiki implementation in description
- [ ] Lessons learned link back to implementation
- [ ] Local input files are deleted after wiki migration
- [ ] `/proposal-status` shows proposal/implementation tree
- [ ] Flexible input: file, conversation, or existing wiki
---
## Implementations
*No implementations yet.*