From 4b96a25137554d5b406f33332af4fd10c262ef3d Mon Sep 17 00:00:00 2001 From: nullhack Date: Fri, 1 May 2026 12:49:49 -0400 Subject: [PATCH 1/4] fix: remove all v7 files not present in v8.0.0 v8_release (02b4070) is the source of truth. These files existed on main from v7 but were intentionally removed in v8.0.0: - Removed: .flowception/, old knowledge files, old skill files, docs/flows/*.yaml, scripts/check_knowledge.py, docs/assets/workflow.svg --- .flowception/.gitkeep | 0 .../knowledge/agent-design/opencode-format.md | 100 ---- .../knowledge/architecture/domain-stubs.md | 95 ---- .../knowledge/architecture/smell-check.md | 62 --- .opencode/knowledge/branding/svg-rules.md | 69 --- .opencode/knowledge/branding/wcag-colors.md | 84 ---- .opencode/knowledge/git/protocol.md | 103 ----- .../requirements/discovery-techniques.md | 87 ---- .../knowledge/requirements/invest-moscow.md | 82 ---- .../knowledge/skill-design/opencode-format.md | 110 ----- .../knowledge/software-craft/code-quality.md | 64 --- .../software-craft/self-declaration.md | 97 ---- .../software-craft/test-conventions.md | 138 ------ .../software-craft/verification-philosophy.md | 49 -- .opencode/knowledge/workflow/state-machine.md | 231 ---------- .opencode/skills/create-knowledge/SKILL.md | 158 ------- docs/assets/workflow.svg | 433 ------------------ docs/flows/arch-cycle.yaml | 41 -- docs/flows/feature-flow.yaml | 72 --- docs/flows/scope-cycle.yaml | 28 -- docs/flows/tdd-cycle.yaml | 30 -- scripts/check_knowledge.py | 292 ------------ 22 files changed, 2425 deletions(-) delete mode 100644 .flowception/.gitkeep delete mode 100644 .opencode/knowledge/agent-design/opencode-format.md delete mode 100644 .opencode/knowledge/architecture/domain-stubs.md delete mode 100644 .opencode/knowledge/architecture/smell-check.md delete mode 100644 .opencode/knowledge/branding/svg-rules.md delete mode 100644 .opencode/knowledge/branding/wcag-colors.md delete mode 100644 .opencode/knowledge/git/protocol.md delete mode 100644 .opencode/knowledge/requirements/discovery-techniques.md delete mode 100644 .opencode/knowledge/requirements/invest-moscow.md delete mode 100644 .opencode/knowledge/skill-design/opencode-format.md delete mode 100644 .opencode/knowledge/software-craft/code-quality.md delete mode 100644 .opencode/knowledge/software-craft/self-declaration.md delete mode 100644 .opencode/knowledge/software-craft/test-conventions.md delete mode 100644 .opencode/knowledge/software-craft/verification-philosophy.md delete mode 100644 .opencode/knowledge/workflow/state-machine.md delete mode 100644 .opencode/skills/create-knowledge/SKILL.md delete mode 100644 docs/assets/workflow.svg delete mode 100644 docs/flows/arch-cycle.yaml delete mode 100644 docs/flows/feature-flow.yaml delete mode 100644 docs/flows/scope-cycle.yaml delete mode 100644 docs/flows/tdd-cycle.yaml delete mode 100755 scripts/check_knowledge.py diff --git a/.flowception/.gitkeep b/.flowception/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/.opencode/knowledge/agent-design/opencode-format.md b/.opencode/knowledge/agent-design/opencode-format.md deleted file mode 100644 index 1105ecf..0000000 --- a/.opencode/knowledge/agent-design/opencode-format.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -domain: agent-design -tags: [agents, opencode, format, configuration] -last-updated: 2026-04-26 ---- - -# OpenCode Agent Format - -## Key Takeaways - -- Agent files live at `.opencode/agents/.md` (project) or `~/.config/opencode/agents/.md` (global); the filename becomes the agent name. -- Frontmatter requires `description` and `mode` (primary/subagent/all); optional fields include model, temperature, steps, permissions, and more. -- Body sections in order: Role, Available Skills, Instructions, Escalation; write in third person. -- Permission values are `allow` (run immediately), `ask` (prompt user), `deny` (hidden/rejected); wildcards supported, last matching rule wins. - -## Concepts - -**File Location and Naming**: Agent files are discovered at `.opencode/agents/.md` (project-level) and `~/.config/opencode/agents/.md` (global). The filename without `.md` becomes the agent name. Project-level takes precedence. - -**YAML Frontmatter Fields**: Required fields are `description` (1-sentence, shown in agent selection) and `mode` (primary for main agents, subagent for agents invoked by others, all for either). Key optional fields: `model` (override default model), `steps` (max agentic iterations), `hidden` (hide subagents from autocomplete), `permission` (fine-grained tool access control), `prompt` (custom system prompt). - -**Body Structure**: Body sections in order: Role (who the agent is and what it owns), Available Skills (which skills to load and when), Instructions (step-by-step actions), Escalation (when to hand off). - -**Permission Patterns**: Permission values are `allow` (run immediately), `ask` (prompt user), `deny` (hidden/rejected); wildcards are supported and the last matching rule wins. Common patterns: Read-only (deny edit, ask bash), Build (allow edit and bash), Restricted (ask for both). - -## Content - -### File Locations - -- Project: `.opencode/agents/.md` -- Global: `~/.config/opencode/agents/.md` - -The filename (without `.md`) becomes the agent name. - -### YAML Frontmatter - -```yaml ---- -description: <1-sentence description> # Required -mode: primary | subagent | all # Required -model: # Optional; inherits from primary -temperature: <0.0-1.0> # Optional; model default -steps: # Optional; max agentic iterations -disable: true | false # Optional; default false -hidden: true | false # Optional; subagent only; hides from @ autocomplete -prompt: # Optional; custom system prompt -color: # Optional; UI color -top_p: <0.0-1.0> # Optional; response diversity -permission: - edit: allow | ask | deny - bash: - "*": ask | allow | deny # Wildcard; last matching rule wins - "git status *": allow # Specific command patterns - webfetch: allow | ask | deny - skill: - "": allow | deny - task: - "*": deny | allow - "": allow ---- -``` - -### Key Fields - -- **description** (required): What the agent does and when to use it. Shown in agent selection. -- **mode**: `primary` for main agents, `subagent` for agents invoked by others, `all` for either. -- **model**: Override the default model. Subagents inherit the invoking primary's model unless specified. -- **steps**: Maximum agentic iterations before forced text-only response. -- **hidden**: Only for `mode: subagent`. Hides from `@` autocomplete but still invokable via Task tool. -- **permission.task**: Controls which subagents this agent can invoke via the Task tool. Glob patterns supported; last matching rule wins. - -### Permission Values - -| Value | Behavior | -|---|---| -| `allow` | Tool runs immediately without approval | -| `ask` | User prompted for approval before running | -| `deny` | Tool hidden from agent, access rejected | - -### Markdown Body - -After frontmatter, write the agent's instructions. Key sections: - -1. **Role** — who the agent is and what it owns -2. **Available Skills** — which skills to load and when -3. **Instructions** — step-by-step actions for each owned step -4. **Escalation** — when to hand off to another agent or human - -### Common Permission Patterns - -| Pattern | edit | bash | Use Case | -|---|---|---|---| -| Read-only | deny | ask (specific: allow git read commands) | Review, analysis | -| Build | allow | allow | Full development | -| Restricted | ask | ask | Planning, cautious editing | - -## Related - -- [[agent-design/principles]] -- [[skill-design/opencode-format]] \ No newline at end of file diff --git a/.opencode/knowledge/architecture/domain-stubs.md b/.opencode/knowledge/architecture/domain-stubs.md deleted file mode 100644 index 0f423fb..0000000 --- a/.opencode/knowledge/architecture/domain-stubs.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -domain: architecture -tags: [domain-analysis, stubs, protocols, file-placement] -last-updated: 2026-04-26 ---- - -# Domain Analysis and Stub Writing - -## Key Takeaways - -- Extract nouns from feature/glossary language as candidate Entities, Value Objects, or Aggregates; verbs as candidate Actions; datasets as named types. -- Write stubs with `...` bodies only — no logic, no conditionals, no docstrings, no imports beyond `typing` and domain types. -- Assign a Protocol for every external dependency (SOLID-D + Hexagonal); if no external dependencies exist, SOLID-D is N/A. -- Place stubs where responsibility dictates; do not pre-create `ports/` or `adapters/` folders unless a concrete external dependency was identified. - -## Concepts - -**Domain Analysis Process**: From `docs/glossary.md` and Rules (Business) in the `.feature` file, nouns become candidate Entities/Value Objects/Aggregates, verbs become candidate Actions, datasets become named types. A bounded context check identifies module boundaries: same word, different meaning across features indicates a boundary. Cross-feature entities become candidates for a shared domain layer. - -**Stub Rules**: Method bodies must be `...` only — no logic, no conditionals, no imports beyond `typing` and domain types. No docstrings (signatures will change; add after GREEN). No inline comments, no TODO comments, no speculative code. Stubs define the shape of the domain; GREEN fills in the behaviour. - -**Protocol Pattern for External Dependencies**: All external dependencies must be assigned a Protocol (SOLID-D + Hexagonal architecture). A Protocol defines the interface; concrete implementations live in adapter modules. If no external dependencies exist in scope, the SOLID-D check is N/A. - -**File Placement Patterns**: Place domain entities and value objects in `/domain/.py`, cross-entity operations in `/domain/service.py`. Place stubs where responsibility dictates. Do not pre-create `ports/` or `adapters/` folders unless a concrete external dependency was identified. Structure follows domain analysis, not a template. - -## Content - -### Domain Analysis Process - -From `docs/glossary.md` + Rules (Business) in the `.feature` file: - -- **Nouns** in feature/glossary language become candidate Entities, Value Objects, or Aggregates in the domain model -- **Verbs** in feature/glossary language become candidate Actions (operations with typed signatures on an Entity, a standalone function, or a Domain Service) -- **Datasets** become named types (not bare dict/list) -- **Bounded Context check**: same word, different meaning across features? That indicates a module boundary -- **Cross-feature entities** become candidates for a shared domain layer - -### Updating the Domain Model - -Update the `## Domain Model` section of `docs/system.md`: - -- **New feature, first entities**: add bounded contexts, entities, actions, and relationships -- **Existing feature**: append new entities and actions. Deprecate old entries by moving them to a `### Deprecated` subsection. Never edit existing live entries — code depends on them -- Update `## Context` section if new actors, external systems, or interactions are identified -- Update `## Container` section if new containers or container interactions are identified - -The PO reads `docs/system.md` but never writes to it. The SA owns this file. - -### Stub Rules (Strictly Enforced) - -- Method bodies must be `...` — no logic, no conditionals, no imports beyond `typing` and domain types -- No docstrings — signatures will change; add docstrings after GREEN (lint enforces this at quality gate) -- No inline comments, no TODO comments, no speculative code - -Example of correct stub style: - -```python -from dataclasses import dataclass -from typing import Protocol - - -@dataclass(frozen=True, slots=True) -class EmailAddress: - value: str - - def validate(self) -> None: ... - - -class UserRepository(Protocol): - def save(self, user: "User") -> None: ... - def find_by_email(self, email: EmailAddress) -> "User | None": ... -``` - -### Protocol Pattern for External Dependencies - -All external dependencies must be assigned a Protocol (SOLID-D + Hexagonal architecture). A Protocol defines the interface; concrete implementations live in adapter modules. This enables dependency inversion and testability. - -If no external dependencies exist in scope, the SOLID-D check is N/A. - -### File Placement Patterns - -Common patterns (not required names): - -- `/domain/.py` — entities, value objects -- `/domain/service.py` — cross-entity operations - -Place stubs where responsibility dictates. Do not pre-create `ports/` or `adapters/` folders unless a concrete external dependency was identified in scope. Structure follows domain analysis, not a template. - -If the file already exists: add the new class or method signature — do not remove or alter existing code. If the file does not exist: create it with the new signatures only. - -## Related - -- [[architecture/smell-check]] — quality gate applied to stubs before commit -- [[architecture/adr]] — recording decisions about protocols and patterns -- [[requirements/gherkin]] — the source of nouns and verbs for domain analysis \ No newline at end of file diff --git a/.opencode/knowledge/architecture/smell-check.md b/.opencode/knowledge/architecture/smell-check.md deleted file mode 100644 index 4b31248..0000000 --- a/.opencode/knowledge/architecture/smell-check.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -domain: architecture -tags: [smell-check, quality-gate, SOLID, patterns, ADR] -last-updated: 2026-04-26 ---- - -# Architecture Smell Check - -## Key Takeaways - -- Verify SOLID-S (one responsibility), OC-8 (≤2 instance variables), SOLID-D + Hexagonal (all external deps have Protocols), and bounded context (no noun with different meaning across modules). -- Check for missing creational patterns (Factory/Builder for repeated complex construction), structural patterns (Strategy/Visitor for type-switching), and behavioral patterns (State/Observer for state machines and notifications). -- Verify ADR consistency: each ADR must be consistent with each acceptance criterion — no contradictions. -- Fix any failing check before committing stubs; re-run the smell check; only commit when all 8 checks pass. - -## Concepts - -**Verify structural and architectural constraints**: The smell check verifies SOLID-S (one responsibility per class), OC-8 (≤2 instance variables per behavioural class), SOLID-D + Hexagonal (all external deps have Protocols), and DDD Bounded Context (no noun with different meaning across modules). - -**Check for missing design patterns**: Verify creational patterns (Factory/Builder for repeated complex construction), structural patterns (Strategy/Visitor for type-switching), and behavioral patterns (State/Observer for state machines and notifications). - -**Verify ADR consistency**: Each ADR must be consistent with each acceptance criterion — no contradictions between architectural decisions and specified behaviour. - -**Fix before committing**: If any check fails, fix the stub files before committing, re-run the smell check, and only commit when all 8 checks pass. - -## Content - -The Architecture Smell Check is applied to all stub files after domain analysis and stub writing, before committing. Every item must pass. - -### Checklist - -- [ ] **SOLID-S**: No class with more than 2 responsibilities. Each class has one reason to change. -- [ ] **OC-8**: No behavioural class with more than 2 instance variables. Dataclasses, Pydantic models, value objects, and TypedDicts are exempt — they are data containers, not behavioural classes. -- [ ] **SOLID-D + Hexagonal**: All external dependencies assigned a Protocol. If no external dependencies exist in scope, this check is N/A. -- [ ] **DDD Bounded Context**: No noun with different meaning across modules. Same word, different meaning indicates a module boundary. -- [ ] **Creational pattern**: No missing Factory/Builder where construction is repeated. If objects are constructed in multiple places with complex logic, extract a Factory or Builder. -- [ ] **Structural pattern**: No missing Strategy/Visitor where type-switching occurs. If code switches on type, apply the appropriate structural pattern. -- [ ] **Behavioral pattern**: No missing State/Observer where a state machine or scattered notification exists. If behaviour depends on state or events need propagation, apply the pattern. -- [ ] **ADR consistency**: Each ADR is consistent with each @id acceptance criterion — no contradictions between architectural decisions and specified behaviour. - -### Failure Protocol - -If any check fails: -1. Fix the stub files before committing -2. Re-run the smell check -3. Only commit when all 8 checks pass - -### When to Apply - -- At the end of Step 2, before committing stubs and ADRs -- Not during Step 3 (TDD loop) — that phase has its own quality gates -- Not during Step 4 (Verification) — the SA uses a different review process - -### Relationship to Design Patterns - -If a pattern smell is detected during the smell check, load `skill apply-patterns` for the appropriate GoF pattern catalogue entry. The smell check identifies the gap; the pattern skill provides the structural solution. - -## Related - -- [[architecture/adr]] — recording architectural decisions that pass the smell check -- [[architecture/domain-stubs]] — writing stubs that satisfy the smell check -- [[requirements/discovery-techniques]] — silent pre-mortem technique used before the smell check \ No newline at end of file diff --git a/.opencode/knowledge/branding/svg-rules.md b/.opencode/knowledge/branding/svg-rules.md deleted file mode 100644 index 33231b6..0000000 --- a/.opencode/knowledge/branding/svg-rules.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -domain: branding -tags: [svg, assets, banner, logo, accessibility] -last-updated: 2026-04-26 ---- - -# SVG Structure Rules - -## Key Takeaways - -- Set `viewBox` on every SVG root; no fixed `width`/`height`; use CSS custom properties for colors with fallback hex. -- Add `role="img"` and `aria-label` on every `` for WCAG 1.1.1 compliance; ensure readability at 400px wide (banners) and 32px (logos). -- Banners use `viewBox="0 0 1200 300"` with a three-zone layout: left accent (20%), center text (60%), right optional graphic (20%). -- Logos use `viewBox="0 0 100 100"` (square) with one recognizable shape readable at 16px; no text in the mark. - -## Concepts - -**SVG Structure Constraints**: All SVGs must follow W3C SVG 2 spec constraints: always set `viewBox`, never fixed dimensions, colors via CSS custom properties with fallback hex, system font stack (no external imports), no external `` refs (raster only if base64-inlined), and WCAG accessibility attributes on every `` element. - -**WCAG Accessibility**: Add `role="img"` and `aria-label` on every `` for WCAG 1.1.1 compliance. Ensure readability at minimum display sizes: 400px wide for banners, 32px for logos. - -**Banner Layout**: Banners use `viewBox="0 0 1200 300"` with three zones: left accent (20%), center title+tagline (60%), right optional graphic (20%). - -**Logo Layout**: Logos use `viewBox="0 0 100 100"` (square) with one recognizable shape readable at 16px, no text in the mark. - -## Content - -### SVG Structure Constraints - -All SVGs must follow these constraints (W3C SVG 2 spec — CSS properties take precedence over presentation attributes; inline `