chore(agents): register feature-selection and refactor skills across all agent files

Author: nullhack

.opencode/agents/product-owner.md

@@ -59,4 +59,5 @@ When a gap is reported (by software-engineer or reviewer):
 ## Available Skills
 
 - `session-workflow` — session start/end protocol
+- `feature-selection` — when TODO.md is idle: score and select next backlog feature using WSJF
 - `scope` — Step 1: 3-session discovery (Phase 1 + 2), stories (Phase 3), and criteria (Phase 4)

.opencode/agents/software-engineer.md

@@ -38,7 +38,7 @@ Load `skill session-workflow` first — it reads TODO.md, orients you to the cur
 | Step | Action |
 |---|---|
 | **Step 2 — ARCH** | Load `skill implementation` — contains Step 2 architecture protocol |
-| **Step 3 — TDD LOOP** | Load `skill implementation` — contains Step 3 TDD Loop |
+| **Step 3 — TDD LOOP** | Load `skill implementation` — contains Step 3 TDD Loop; load `skill refactor` when entering REFACTOR phase or doing preparatory refactoring |
 | **Step 5 — after PO accepts** | Load `skill pr-management` and `skill git-release` as needed |
 
 ## Ownership Rules
@@ -57,7 +57,8 @@ If during implementation you discover behavior not covered by existing acceptanc
 
 - `session-workflow` — session start/end protocol
 - `implementation` — Steps 2-3: architecture + TDD loop
-- `design-patterns` — on-demand when smell detected during refactor
+- `refactor` — REFACTOR phase and preparatory refactoring (load on-demand)
+- `design-patterns` — on-demand when smell detected during architecture or refactor
 - `pr-management` — Step 5: PRs with conventional commits
 - `git-release` — Step 5: calver versioning and themed release naming
 - `create-skill` — meta: create new skills when needed

.opencode/skills/create-skill/SKILL.md

@@ -27,7 +27,7 @@ Before writing any skill, research the domain to ground the skill in industry st
    - Vendor documentation (OpenAI, Anthropic, Google, Microsoft)
    - Industry standards (ISO, NIST, OMG)
    - Established methodologies (e.g., FDD, Scrum, Kanban for process skills)
-3. **Read existing research**: Check `docs/academic_research.md` for related entries
+3. **Read existing research**: Check `docs/scientific-research/` for related entries — each file covers a domain (testing, oop-design, architecture, ai-agents, etc.)
 4. **Synthesize conclusions**: Extract actionable conclusions — what works, why, and when to apply it
 5. **Embed as guidance**: Write the skill's steps, checklists, and decision rules based on those conclusions — not as academic citations but as direct guidance ("Use X because it produces Y outcome")
 
@@ -133,6 +133,7 @@ Add the skill name to the agent's "Available Skills" section so the agent knows
 | Skill | Used By | Purpose |
 |---|---|---|
 | `session-workflow` | all agents | Session start/end protocol |
+| `feature-selection` | product-owner | Score and select next backlog feature (WSJF) |
 | `scope` | product-owner | Step 1: define acceptance criteria |
 | `implementation` | software-engineer | Steps 2-3: architecture + TDD loop |
 | `design-patterns` | software-engineer | Steps 2, 3: refactor when smell detected |

AGENTS.md

@@ -11,7 +11,7 @@ Features flow through 5 steps with a WIP limit of 1 feature at a time. The files
 
 ```
 STEP 1: SCOPE          (product-owner)  → discovery + Gherkin stories + criteria
-STEP 2: ARCH           (software-engineer)      → read all backlog features, design module structure
+STEP 2: ARCH           (software-engineer)      → read all features + existing package files, write domain stubs (signatures only, no bodies); ADRs to docs/architecture/
 STEP 3: TDD LOOP       (software-engineer)      → RED → GREEN → REFACTOR, one @id at a time
 STEP 4: VERIFY         (reviewer)       → run all commands, review code
 STEP 5: ACCEPT         (product-owner)  → demo, validate, move folder to completed/
@@ -40,9 +40,11 @@ STEP 5: ACCEPT         (product-owner)  → demo, validate, move folder to compl
 | Skill | Used By | Step |
 |---|---|---|
 | `session-workflow` | all agents | every session |
+| `feature-selection` | product-owner | between features (idle state) |
 | `scope` | product-owner | 1 |
 | `implementation` | software-engineer | 2, 3 |
-| `design-patterns` | software-engineer | 2 (on-demand, if smell detected), 3 (refactor) |
+| `design-patterns` | software-engineer | 2, 3 (on-demand, when GoF pattern needed) |
+| `refactor` | software-engineer | 3 (REFACTOR phase + preparatory refactoring) |
 | `verify` | reviewer | 4 |
 | `code-quality` | software-engineer | pre-handoff (redirects to `verify`) |
 | `pr-management` | software-engineer | 5 |
@@ -87,6 +89,10 @@ docs/features/
   in-progress/<feature-name>.feature  ← file moves here at Step 2
   completed/<feature-name>.feature    ← file moves here at Step 5
 
+docs/architecture/
+  STEP2-ARCH.md                       ← Step 2 reference diagram (canonical)
+  adr-NNN-<title>.md                  ← one per significant architectural decision
+
 tests/
   features/<feature-name>/
     <rule-slug>_test.py               ← one per Rule: block, software-engineer-written