Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor: align repo with marketplace/plugin model — migrate docs and issues to Gitea, rewrite specs, clean up stale artifacts #15

New Issue
Closed
opened 2026-06-28 16:09:11 +00:00 by Claude · 4 comments
Claude commented 2026-06-28 16:09:11 +00:00
Collaborator
Copy Link

Context

The repo was originally structured around a chunk-based delivery model with local docs/issues/ and docs/prd/ files as the issue tracker. Since the marketplace/plugin pivot, this is no longer the model — plugins are the deployable unit, Gitea is the issue tracker, and the skills deployment path has changed entirely. This refactor brings the repo's docs, context, and structure into alignment with how it actually works today.

Scoped in a grill session (2026-06-28). Independent of the Kyberforge basics milestone — can run in parallel.

Scope

1. Migrate docs/issues/ to Gitea

All 28 local issue files (0001–0028) migrate to Gitea.

  • Completed issues (0001–0018, chunks 1–3 bootstrap, governance, factory bootstrap) → closed Gitea issues
  • Open issues (0019–0028, remaining factory skill groups + chunk closure) → open Gitea issues
  • All land in a new triage/placeholder milestone first — to be reviewed and redistributed after this refactor, since the chunk framing is superseded
  • Delete docs/issues/ directory after migration

2. Migrate docs/prd/ to Gitea

Three PRD files (chunk-1, chunk-2-instructions, chunk-3-skills-library) → closed Gitea issues. These are completed design artifacts.

  • Delete docs/prd/ directory after migration

3. Create triage milestone

Create a catch-all Gitea milestone (e.g. "Legacy / Triage") to receive all migrated issues. Issues will be re-evaluated and redistributed to real milestones in a follow-on workstream.

4. Slim ROADMAP.md

Strip down to a nav page only: purpose of the repo, pointer to Gitea milestones for current work, pointer to docs/spec/overview.md for deployed state. Remove the chunk table, housekeeping reminders, and open questions table — all superseded by Gitea or absorbed into other docs.

5. Rewrite docs/spec/overview.md

Full rewrite to reflect the plugin model:

  • List all 5 plugins (kyberforge, bin, core, git, gitea), their contents, and install commands
  • Drop "Chunk 3 target: 42 skills" and all chunk framing
  • Update "What is deployed" and "What is not yet deployed" to reflect current state
  • Update "Recent changes" section

6. Rewrite docs/spec/architecture.md

Full rewrite — equally stale as overview.md:

  • Drop .agents/skills/ as the main content location (that directory no longer exists in the repo)
  • Update directory structure to show current plugin layout (all 5 plugins)
  • Remove references to sync.sh and init-project.sh as existing scripts (they are Chunk 6, not yet built)
  • Reflect actual install.sh behaviour (deploys core files only; skills come from plugin installs)

7. Update CONTEXT.md

  • Docs convention section: remove docs/prd/<slug> and docs/issues/NNNN-<slug>.md entries — both directories are gone
  • Issue tracker glossary entry: simplify "Provider-agnostic issue tracker" — drop the "file-based phase" framing; Gitea is the tracker
  • Add LESSONS.md glossary entry: the description currently lives in ROADMAP.md ("long-loop feedback log; three or more entries on the same pattern graduate to the relevant standing file"). Move it here so it survives the ROADMAP slim-down.

8. Archive stale notes

Move docs/notes/ai-ethics-security-principles.md and docs/notes/team-self-organisation-sprint-brief.md to docs/notes/archive/. Both are superseded or out of scope — ai-ethics-security-principles.md is explicitly marked superseded in ROADMAP.md.

9. Delete stale bin skills

Remove to-issues and to-prd from plugins/bin/skills/. Both are stale mattpocock adoptions with /setup-matt-pocock-skills references that don't exist here, and neither explicitly targets Gitea. Replacement: issue-author agent (tracked separately under Kyberforge basics milestone).

10. Clean up install.sh

Remove dead .agents/skills/ deployment code. The comment says "Skipped when source does not exist" — the directory doesn't exist and won't return. The code and comments are noise.

11. ADR-0017 — Gitea as canonical issue tracker ✅ written

Already committed to docs/adr/0017-gitea-canonical-issue-tracker.md during the scoping grill session. Supersedes ADR-0011.

12. Triage all ADRs (0001–0017)

ADRs are treated as mutable for this refactor. Review each against current repo model — rewrite, update, or delete where the underlying decision has changed.

Known issues going in:

  • ADR-0004 (skills-in-agents-dir): definitively stale. Says skills live in .agents/skills/ as the canonical repo source, deployed via install.sh. Neither is true — source is now plugins/<name>/skills/, distribution is claude plugin install. Needs rewrite.
  • ADR-0005 (two-tier-claude-md): still valid. Add a cross-reference to ADR-0012 which extends it.
  • ADR-0011 (provider-agnostic-issue-tracker): superseded by ADR-0017. Update with a superseded-by note or delete.
  • ADR-0001–0003, 0006–0010, 0012–0016: likely current — verify during triage pass.

13. Update docs/VISION.md — remove chunk framing

VISION.md still references the chunk delivery model in four places:

  • Line 22: init-project.sh comes in chunk 6
  • Line 23: GitHub Copilot support (chunk 7)
  • Line 35: Everything from chunk 2 onward...
  • Line 59: after Chunk 6 of this repo (sync.sh + init-project.sh)

Replace chunk references with plugin model framing. The vision content itself is still valid — only the delivery sequencing language is stale.

14. Remove stale .agents/skills/ blocks from tests/test-install.sh

Lines 62–144 test deploying skills from .agents/skills/, which no longer exists in the repo. These tests silently no-op today. Remove the dead test blocks; the coverage gap (plugin-based skill deployment) is a separate concern and out of scope here.

15. Clean up scripts/deploy-manifest.sh

Two stale references:

  • Line 2 comment: sourced by install.sh and sync.sh (Chunk 6) — sync.sh does not exist; remove the reference
  • Line 25: DEPLOY_SKILLS_SRC=".agents/skills" — the old source path; remove or update to reflect the plugin model

Acceptance criteria

  • All 28 docs/issues/ files exist as Gitea issues; docs/issues/ directory deleted
  • All 3 docs/prd/ files exist as Gitea issues (closed); docs/prd/ directory deleted
  • Triage milestone created and all migrated issues assigned to it
  • ROADMAP.md deleted (exceeded nav-page target)
  • docs/spec/overview.md deleted; all references scrubbed (chunk model superseded — rewrite not needed)
  • docs/spec/architecture.md describes current state; no .agents/skills/ deployment model
  • CONTEXT.md docs convention has no docs/prd/ or docs/issues/ entries
  • CONTEXT.md issue tracker glossary entry has no "file-based phase" language
  • CONTEXT.md has a LESSONS.md glossary entry
  • docs/notes/archive/ exists with both stale notes moved in
  • plugins/bin/skills/to-issues/ and plugins/bin/skills/to-prd/ deleted
  • install.sh has no dead .agents/skills/ deployment code
  • ADR-0017 committed to docs/adr/ ✅
  • All 17 ADRs reviewed; stale ones rewritten, updated, or deleted; ADR-0004 rewritten, ADR-0011 resolved
  • docs/VISION.md has no chunk references; delivery sequencing reflects plugin model
  • tests/test-install.sh has no .agents/skills/ test blocks
  • scripts/deploy-manifest.sh has no sync.sh (Chunk 6) comment or .agents/skills source path

Sequencing note

Items 1–3 (migration + triage milestone) are the natural starting point — they clear the local artifact directories and give Gitea the full issue history. Items 4–7 (docs rewrites) and item 12 (ADR triage) can run in parallel once the directories are gone. Items 8–11 are independent cleanup that can happen in any order. Items 13–15 are independent of everything else and can be picked up at any point.

## Context The repo was originally structured around a chunk-based delivery model with local `docs/issues/` and `docs/prd/` files as the issue tracker. Since the marketplace/plugin pivot, this is no longer the model — plugins are the deployable unit, Gitea is the issue tracker, and the skills deployment path has changed entirely. This refactor brings the repo's docs, context, and structure into alignment with how it actually works today. Scoped in a grill session (2026-06-28). Independent of the Kyberforge basics milestone — can run in parallel. --- ## Scope ### 1. Migrate `docs/issues/` to Gitea All 28 local issue files (0001–0028) migrate to Gitea. - Completed issues (0001–0018, chunks 1–3 bootstrap, governance, factory bootstrap) → closed Gitea issues - Open issues (0019–0028, remaining factory skill groups + chunk closure) → open Gitea issues - All land in a new **triage/placeholder milestone** first — to be reviewed and redistributed after this refactor, since the chunk framing is superseded - Delete `docs/issues/` directory after migration ### 2. Migrate `docs/prd/` to Gitea Three PRD files (chunk-1, chunk-2-instructions, chunk-3-skills-library) → closed Gitea issues. These are completed design artifacts. - Delete `docs/prd/` directory after migration ### 3. Create triage milestone Create a catch-all Gitea milestone (e.g. "Legacy / Triage") to receive all migrated issues. Issues will be re-evaluated and redistributed to real milestones in a follow-on workstream. ### 4. Slim `ROADMAP.md` Strip down to a nav page only: purpose of the repo, pointer to Gitea milestones for current work, pointer to `docs/spec/overview.md` for deployed state. Remove the chunk table, housekeeping reminders, and open questions table — all superseded by Gitea or absorbed into other docs. ### 5. Rewrite `docs/spec/overview.md` Full rewrite to reflect the plugin model: - List all 5 plugins (`kyberforge`, `bin`, `core`, `git`, `gitea`), their contents, and install commands - Drop "Chunk 3 target: 42 skills" and all chunk framing - Update "What is deployed" and "What is not yet deployed" to reflect current state - Update "Recent changes" section ### 6. Rewrite `docs/spec/architecture.md` Full rewrite — equally stale as overview.md: - Drop `.agents/skills/` as the main content location (that directory no longer exists in the repo) - Update directory structure to show current plugin layout (all 5 plugins) - Remove references to `sync.sh` and `init-project.sh` as existing scripts (they are Chunk 6, not yet built) - Reflect actual `install.sh` behaviour (deploys core files only; skills come from plugin installs) ### 7. Update `CONTEXT.md` - **Docs convention section**: remove `docs/prd/<slug>` and `docs/issues/NNNN-<slug>.md` entries — both directories are gone - **Issue tracker glossary entry**: simplify "Provider-agnostic issue tracker" — drop the "file-based phase" framing; Gitea is the tracker - **Add `LESSONS.md` glossary entry**: the description currently lives in ROADMAP.md ("long-loop feedback log; three or more entries on the same pattern graduate to the relevant standing file"). Move it here so it survives the ROADMAP slim-down. ### 8. Archive stale notes Move `docs/notes/ai-ethics-security-principles.md` and `docs/notes/team-self-organisation-sprint-brief.md` to `docs/notes/archive/`. Both are superseded or out of scope — `ai-ethics-security-principles.md` is explicitly marked superseded in ROADMAP.md. ### 9. Delete stale `bin` skills Remove `to-issues` and `to-prd` from `plugins/bin/skills/`. Both are stale mattpocock adoptions with `/setup-matt-pocock-skills` references that don't exist here, and neither explicitly targets Gitea. Replacement: `issue-author` agent (tracked separately under Kyberforge basics milestone). ### 10. Clean up `install.sh` Remove dead `.agents/skills/` deployment code. The comment says "Skipped when source does not exist" — the directory doesn't exist and won't return. The code and comments are noise. ### 11. ADR-0017 — Gitea as canonical issue tracker ✅ written Already committed to `docs/adr/0017-gitea-canonical-issue-tracker.md` during the scoping grill session. Supersedes ADR-0011. ### 12. Triage all ADRs (0001–0017) ADRs are treated as mutable for this refactor. Review each against current repo model — rewrite, update, or delete where the underlying decision has changed. Known issues going in: - **ADR-0004** (skills-in-agents-dir): definitively stale. Says skills live in `.agents/skills/` as the canonical repo source, deployed via `install.sh`. Neither is true — source is now `plugins/<name>/skills/`, distribution is `claude plugin install`. Needs rewrite. - **ADR-0005** (two-tier-claude-md): still valid. Add a cross-reference to ADR-0012 which extends it. - **ADR-0011** (provider-agnostic-issue-tracker): superseded by ADR-0017. Update with a superseded-by note or delete. - **ADR-0001–0003, 0006–0010, 0012–0016**: likely current — verify during triage pass. ### 13. Update `docs/VISION.md` — remove chunk framing VISION.md still references the chunk delivery model in four places: - Line 22: `init-project.sh comes in chunk 6` - Line 23: `GitHub Copilot support (chunk 7)` - Line 35: `Everything from chunk 2 onward...` - Line 59: `after Chunk 6 of this repo (sync.sh + init-project.sh)` Replace chunk references with plugin model framing. The vision content itself is still valid — only the delivery sequencing language is stale. ### 14. Remove stale `.agents/skills/` blocks from `tests/test-install.sh` Lines 62–144 test deploying skills from `.agents/skills/`, which no longer exists in the repo. These tests silently no-op today. Remove the dead test blocks; the coverage gap (plugin-based skill deployment) is a separate concern and out of scope here. ### 15. Clean up `scripts/deploy-manifest.sh` Two stale references: - Line 2 comment: `sourced by install.sh and sync.sh (Chunk 6)` — `sync.sh` does not exist; remove the reference - Line 25: `DEPLOY_SKILLS_SRC=".agents/skills"` — the old source path; remove or update to reflect the plugin model --- ## Acceptance criteria - [x] All 28 `docs/issues/` files exist as Gitea issues; `docs/issues/` directory deleted - [x] All 3 `docs/prd/` files exist as Gitea issues (closed); `docs/prd/` directory deleted - [x] Triage milestone created and all migrated issues assigned to it - [x] `ROADMAP.md` deleted (exceeded nav-page target) - [x] `docs/spec/overview.md` deleted; all references scrubbed (chunk model superseded — rewrite not needed) - [x] `docs/spec/architecture.md` describes current state; no `.agents/skills/` deployment model - [x] `CONTEXT.md` docs convention has no `docs/prd/` or `docs/issues/` entries - [x] `CONTEXT.md` issue tracker glossary entry has no "file-based phase" language - [x] `CONTEXT.md` has a `LESSONS.md` glossary entry - [x] `docs/notes/archive/` exists with both stale notes moved in - [x] `plugins/bin/skills/to-issues/` and `plugins/bin/skills/to-prd/` deleted - [x] `install.sh` has no dead `.agents/skills/` deployment code - [x] ADR-0017 committed to `docs/adr/` ✅ - [x] All 17 ADRs reviewed; stale ones rewritten, updated, or deleted; ADR-0004 rewritten, ADR-0011 resolved - [x] `docs/VISION.md` has no chunk references; delivery sequencing reflects plugin model - [x] `tests/test-install.sh` has no `.agents/skills/` test blocks - [x] `scripts/deploy-manifest.sh` has no `sync.sh (Chunk 6)` comment or `.agents/skills` source path --- ## Sequencing note Items 1–3 (migration + triage milestone) are the natural starting point — they clear the local artifact directories and give Gitea the full issue history. Items 4–7 (docs rewrites) and item 12 (ADR triage) can run in parallel once the directories are gone. Items 8–11 are independent cleanup that can happen in any order. Items 13–15 are independent of everything else and can be picked up at any point.
Claude added this to the The great refactoring milestone 2026-06-28 16:09:11 +00:00
Claude added the Kind/Enhancement
Reviewed
Confirmed
1
Priority
High
2
 labels 2026-06-28 16:09:11 +00:00
Claude commented 2026-06-28 16:51:18 +00:00
Author
Collaborator
Copy Link

PRD migration complete

All PRD files migrated to Gitea as closed issues in the Legacy / Triage milestone. Note: the issue scope listed 3 PRD files but there were actually 4 — governance-instruction-layer.md was also present.

Issue File Notes
#16 chunk-1.md Complete
#17 chunk-2-instructions.md Complete
#18 governance-instruction-layer.md Phase 1 complete; Phase 2 is Chunk 6 scope
#19 chunk-3-skills-library.md Closed as superseded, not complete. Remaining work (issues 0019–0028) is still pending migration to Gitea as open issues.

docs/prd/ directory deleted in commit 8ccb342.

Acceptance criterion: All 3 docs/prd/ files exist as Gitea issues (closed); docs/prd/ directory deleted → Done (4 files, not 3).

## PRD migration complete All PRD files migrated to Gitea as closed issues in the **Legacy / Triage** milestone. Note: the issue scope listed 3 PRD files but there were actually 4 — `governance-instruction-layer.md` was also present. | Issue | File | Notes | |---|---|---| | #16 | `chunk-1.md` | Complete | | #17 | `chunk-2-instructions.md` | Complete | | #18 | `governance-instruction-layer.md` | Phase 1 complete; Phase 2 is Chunk 6 scope | | #19 | `chunk-3-skills-library.md` | **Closed as superseded**, not complete. Remaining work (issues 0019–0028) is still pending migration to Gitea as open issues. | `docs/prd/` directory deleted in commit 8ccb342. Acceptance criterion: ~~All 3 `docs/prd/` files exist as Gitea issues (closed); `docs/prd/` directory deleted~~ → **Done** (4 files, not 3).
Claude commented 2026-06-28 17:14:45 +00:00
Author
Collaborator
Copy Link

Issue migration complete

All 28 docs/issues/ files migrated to Gitea as issues. docs/issues/ directory deleted in commit 49567e4.

File range Gitea issues State
0001–0014 #20, #21, #23, #25–#27, #29, #30, #32, #33, #35, #38, #40, #42 Closed
0015–0018 #22, #24, #28, #31 Closed
0019–0028 #34, #36, #37, #39, #41, #43–#47 Open

All assigned to milestone Legacy / Triage (ID 5).

Acceptance criterion: All 28 docs/issues/ files exist as Gitea issues; docs/issues/ directory deleted → Done.

## Issue migration complete All 28 `docs/issues/` files migrated to Gitea as issues. `docs/issues/` directory deleted in commit 49567e4. | File range | Gitea issues | State | |---|---|---| | 0001–0014 | #20, #21, #23, #25–#27, #29, #30, #32, #33, #35, #38, #40, #42 | Closed | | 0015–0018 | #22, #24, #28, #31 | Closed | | 0019–0028 | #34, #36, #37, #39, #41, #43–#47 | Open | All assigned to milestone **Legacy / Triage** (ID 5). Acceptance criterion: ~~All 28 `docs/issues/` files exist as Gitea issues; `docs/issues/` directory deleted~~ → **Done**.
Claude commented 2026-06-28 19:54:13 +00:00
Author
Collaborator
Copy Link

Completed: spec cleanup (items 5 & 6)

docs/spec/overview.md — deleted rather than rewritten. The file described the chunk-based delivery model (skill counts, chunk targets, recent changes log) which has no equivalent in the plugin model. A rewrite would have been empty prose; deletion was the right call. All cross-references scrubbed from AGENTS.md, CONTEXT.md, docs/notes/factory-integration-decisions.md, docs/notes/factory-research-gaps-conflicts.md, and docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md.

docs/spec/architecture.md — fully rewritten. Key changes:

  • Removed .agents/skills/ as canonical skills source (directory doesn't exist)
  • Removed provider-manifest.sh / symlink mechanism (described but never built)
  • Removed sync.sh and init-project.sh references (Chunk 6, not yet built)
  • Removed stale directory structure diagram
  • Content deployment model now reflects actual install.sh behaviour: three manifest categories (DEPLOY_FILES, DEPLOY_EXECUTABLES, DEPLOY_DIRS); explicit note that skills are not deployed by install.sh
  • Added Plugin model section with table of all 5 plugins
  • Fixed docs/HUMANS.md → docs/wiki/HUMANS.md in governance phase description
  • "Chunk 6" → "planned" in Phase 2 label; "chunk workflow" removed from AGENTS.md description

core/instructions/governance.md — fixed same broken docs/HUMANS.md path.

Commit: 3b5b1b5

## Completed: spec cleanup (items 5 & 6) **`docs/spec/overview.md`** — deleted rather than rewritten. The file described the chunk-based delivery model (skill counts, chunk targets, recent changes log) which has no equivalent in the plugin model. A rewrite would have been empty prose; deletion was the right call. All cross-references scrubbed from `AGENTS.md`, `CONTEXT.md`, `docs/notes/factory-integration-decisions.md`, `docs/notes/factory-research-gaps-conflicts.md`, and `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md`. **`docs/spec/architecture.md`** — fully rewritten. Key changes: - Removed `.agents/skills/` as canonical skills source (directory doesn't exist) - Removed `provider-manifest.sh` / symlink mechanism (described but never built) - Removed `sync.sh` and `init-project.sh` references (Chunk 6, not yet built) - Removed stale directory structure diagram - Content deployment model now reflects actual `install.sh` behaviour: three manifest categories (`DEPLOY_FILES`, `DEPLOY_EXECUTABLES`, `DEPLOY_DIRS`); explicit note that skills are not deployed by install.sh - Added **Plugin model** section with table of all 5 plugins - Fixed `docs/HUMANS.md` → `docs/wiki/HUMANS.md` in governance phase description - "Chunk 6" → "planned" in Phase 2 label; "chunk workflow" removed from AGENTS.md description **`core/instructions/governance.md`** — fixed same broken `docs/HUMANS.md` path. Commit: 3b5b1b5
Claude commented 2026-07-04 17:19:13 +00:00
Author
Collaborator
Copy Link

All 15 acceptance criteria met. ADRs triaged, rewritten, renumbered to 0001-0009, and content audited for alignment with plugin model. All stale chunk-era decisions archived. Pushed in commit 05bb9d6.

All 15 acceptance criteria met. ADRs triaged, rewritten, renumbered to 0001-0009, and content audited for alignment with plugin model. All stale chunk-era decisions archived. Pushed in commit 05bb9d6.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Enhancement
Priority
High
2
Reviewed
Confirmed
1
Milestone
No items
No Milestone The great refactoring
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#15
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?