[LOADED_DOCS: 3 files, no new loads]
Add META topic, CONSUMERS.md, and refine ADR/Framework rules - Introduced META topic with META_ISSUES.md and META_TODO.md for protocol meta-tooling tracking. - Updated TOPIC_CODES.md to register META topic. - Added CONSUMERS.md to document consumer repos per Framework-First exception. - Extended Framework-First rule to all docs, documenting the CONSUMERS.md exception. - Refined adr-author skill: explicit ADR keyword triggers, complexity-based ask-back, and clarified non-trigger cases. - Improves meta-tooling governance, cross-layer doc boundaries, and ADR process.
This commit is contained in:
parent
c062ded9a4
commit
fc63be3226
File diff suppressed because one or more lines are too long
|
|
@ -0,0 +1,48 @@
|
|||
# META — Known Issues (workspace meta-tooling)
|
||||
|
||||
For planned/actionable work see `META_TODO.md`.
|
||||
|
||||
Active issues for the workspace meta-tooling itself: protocol stack, skills, registry conventions, `.github/` files. Distinct from code-domain topics (LOG, BIN, SIG, etc.) which track code/feature concerns.
|
||||
|
||||
## In scope
|
||||
|
||||
- Skill correctness or coverage gaps (`docs-discovery`, `docs-check`, `protocol-audit`, `adr-author`, `docs-archive`)
|
||||
- Registry / convention drift (`REPO_PREFIXES.md`, `TOPIC_CODES.md`, `protocol-audit/references/REPOS.md`)
|
||||
- Protocol-stack inconsistencies (Rule #1-6 wording, `@repo` block format, ID-format edge cases)
|
||||
- `.github/` infrastructure issues (folder structure, file naming conventions, generation rules)
|
||||
- ADR / Decision Log governance issues (e.g., `Current protocol state` summary staleness)
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Code-domain issues (those go to `LOG_ISSUES.md`, `BIN_ISSUES.md`, etc.)
|
||||
- One-off historical events — those go to `LLM_PROTOCOL_DECISIONS.md` as decisions
|
||||
- Forward-looking work that has been formally decided — that's a TODO (`META_TODO.md`) not an issue
|
||||
|
||||
## Active entries
|
||||
|
||||
*(No `ACCORE-META-I-*` entries yet — file just created (LLMP-DEC-62). Add the first entry below as concrete issues are observed.)*
|
||||
|
||||
## Issue entry template
|
||||
|
||||
```
|
||||
## ACCORE-META-I-XXXX: Short title
|
||||
|
||||
**Severity:** Trivial / Low / Minor / Major / Critical · **Status:** Open / InProgress / Closed (YYYY-MM-DD) · **Area:** <skill / registry / convention name>
|
||||
|
||||
### Description
|
||||
What's broken or inconsistent in the meta-tooling, with quotable evidence (file path + line number, or skill behaviour).
|
||||
|
||||
### Root cause
|
||||
Why it's like that.
|
||||
|
||||
### Fix direction
|
||||
Proposed approach.
|
||||
|
||||
### Resolution
|
||||
(Filled when Status moves to `Closed` — what / where / why per `TOPIC_CODES.md` Status conventions.)
|
||||
|
||||
### Related
|
||||
- Sibling: `META_TODO.md#accore-meta-t-xxxx` (if applicable)
|
||||
- Cross-topic: `<other-topic>_ISSUES.md#accore-...` (if domain-spillover)
|
||||
- LLMP-DEC: `LLMP-DEC-N` (if a decision documents the resolution)
|
||||
```
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
|
|
@ -12,29 +12,62 @@ Structured interview-style skill that captures architecturally significant decis
|
|||
|
||||
## When to invoke
|
||||
|
||||
### Explicit user triggers
|
||||
- "tervezzük meg X", "let's plan X", "design the W module"
|
||||
### Explicit ADR invocation (auto-trigger — no ask-back)
|
||||
|
||||
User message contains the literal keyword **"ADR"** or **"Architecture Decision Record"** (case-insensitive, any language):
|
||||
- "create an ADR for X", "write a decision record about Y"
|
||||
- "csináljunk egy ADR-t Z-re", "ez ADR-érdemes"
|
||||
- "this is ADR-worthy"
|
||||
|
||||
→ **Invoke directly**, proceed to Step 1. Skip the complexity sniff. The user has explicitly named the formal mode.
|
||||
|
||||
### Implicit planning request (ASK BACK first if complex)
|
||||
|
||||
User uses planning/design language **WITHOUT** the "ADR" keyword:
|
||||
- "tervezzük meg X", "let's plan X"
|
||||
- "design the W module"
|
||||
- "döntsük el Y vagy Z", "decide between Y and Z"
|
||||
- "válasszunk <tech-stack/library/pattern>", "choose an approach to V"
|
||||
- "milyen megközelítést", "what's our approach to W"
|
||||
- "create an ADR for …", "write a decision record about …"
|
||||
- "válasszunk approach-ot V-re", "choose an approach to V"
|
||||
- "milyen megközelítés", "what's our approach to W"
|
||||
|
||||
### LLM-suggest-back (you flag, user confirms)
|
||||
→ Apply the **complexity sniff** below. If ANY one heuristic fires, **ask back** — do not auto-invoke. If none fires, the request is treated as conversational planning (structured response, but no ADR file).
|
||||
|
||||
When the current conversation exhibits **two or more** of these heuristics, flag the user:
|
||||
**Complexity sniff** (any single one is enough to trigger the ask):
|
||||
- **Cross-cutting** — touches ≥ 2 topics (LOG + SIG, BIN + TOON, etc.)
|
||||
- **Cross-repo** — touches ≥ 2 repos (especially framework↔consumer boundary)
|
||||
- **Reversibility low** — DB schema change, public API shape, breaking change, deployment-affecting
|
||||
- **≥ 2 valid alternative approaches** mentioned or implied
|
||||
- **Vocabulary signals**: "design", "approach", "strategy", "decide between", "choose", "alternatives" (vs. "tweak", "rename", "fix")
|
||||
- **Re-openable question** — something someone might reasonably re-open in 6-18 months asking "wait, why did we pick this?"
|
||||
- **New public-facing API** shape being shaped
|
||||
|
||||
- Multiple alternatives being actively weighed
|
||||
- Decision that is irreversible or expensive to reverse
|
||||
- Cross-cutting impact (touches 2+ modules, or framework↔consumer boundary)
|
||||
- A question someone might reasonably re-open in 6-18 months and ask "wait, why did we pick this?"
|
||||
- Non-trivial dependency or library choice
|
||||
- New public-facing API shape being discussed
|
||||
**Ask-back template** (LLM emits this; waits for user response BEFORE invoking):
|
||||
|
||||
Example flag phrasing:
|
||||
> "Ez ADR-érdemesnek tűnik mert {concrete heuristic 1, heuristic 2 — name them}. Akarsz formális ADR-t (`adr-author` skill: kontextus → alternatívák → trade-offs → döntés → következmények, durable `.md` artifact-tal) — vagy elég egy gyors strukturált terv (válasz formájában, fájl nélkül)?"
|
||||
|
||||
> "Ez egy architektúra-szintű választásnak tűnik (több alternatíva, irreverzibilis lehet). Érdemes lenne ADR-formába önteni — invokáljam az `adr-author` skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)"
|
||||
**User response paths**:
|
||||
- "yes" / "formal ADR" / "igen ADR" / "csináljuk" / "mehet az ADR" → proceed to Step 1
|
||||
- "no" / "quick plan" / "gyors terv" / "csak egy terv" → DO NOT invoke this skill; respond conversationally with a structured plan (bullet points, alternatives if any, recommendation — but no `.md` artifact created)
|
||||
- Ambiguous → ask follow-up question, do NOT auto-invoke. Default = ASK rather than guess.
|
||||
|
||||
**User confirmation is required** before proceeding to Step 1. Never auto-invoke.
|
||||
### Trivial — no ADR, no ask-back
|
||||
|
||||
Obviously small request the LLM can confidently classify:
|
||||
- Method rename, variable rename
|
||||
- Single-file typo fix
|
||||
- Isolated bug fix (already-understood problem)
|
||||
- Doc tweak (formatting, link update, single-paragraph rewrite)
|
||||
- Code-comment improvement
|
||||
|
||||
→ Just do the work. No ADR ask-back. No invocation.
|
||||
|
||||
### Proactive flag (drift into architectural territory)
|
||||
|
||||
When the conversation drifts into architecturally significant territory **WITHOUT** the user's explicit planning request — e.g., a "how does X work" thread that surfaces 2 alternative implementations the user is now mentally weighing — the LLM may proactively flag:
|
||||
|
||||
> "Ez a beszélgetés architektúra-szintű választáshoz vezet ({observation — what specific signals you saw}). Érdemes lenne ADR-formába önteni — invokáljam az `adr-author` skill-t? (Jelezd, ha inkább folytassuk simán válaszként.)"
|
||||
|
||||
Same complexity sniff as the implicit-planning case. **User confirmation always required** — never auto-invoke from a drift signal.
|
||||
|
||||
### When NOT to invoke
|
||||
- Trivial decisions: variable names, local refactors, formatting
|
||||
|
|
|
|||
|
|
@ -19,6 +19,7 @@ To make IDs like `ACCORE-LOG-I-K7M2`, `ACCORE-SIG-B-3R9P`, `ACCORE-XCUT-I-A4B7`
|
|||
| `BIN` | BINARY | AcBinary serializer: features, format, writers, source generator | `AyCode.Core/AyCode.Core/docs/BINARY/` |
|
||||
| `TOON` | TOON | Toon serializer: LLM-optimized format with @meta/@types/@data sections | `AyCode.Core/AyCode.Core/docs/TOON/` |
|
||||
| `XCUT` | cross-cutting | Issues / TODOs spanning ≥2 ACCORE topics — one canonical home, referenced from each affected topic | `AyCode.Core/AyCode.Core/docs/XCUT/` |
|
||||
| `META` | meta-tooling | Issues/TODOs **about the workspace meta-tooling itself**: skills, registries, `.github/` conventions, ADR/Decision Log governance, protocol-stack edge cases. Distinct from code-domain topics (LOG, BIN, etc.). | `AyCode.Core/.github/META_ISSUES.md` + `AyCode.Core/.github/META_TODO.md` |
|
||||
| `LLMP` | LLM-protocol meta | LLM protocol decisions (Decision Log entries only — uses `LLMP-DEC-N` form, no prefix) | `AyCode.Core/.github/LLM_PROTOCOL_DECISIONS.md` |
|
||||
|
||||
## Type codes (universal across all repos)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
# AyCode.Core — Consumer Workspace Map
|
||||
|
||||
> **Bounded consumer-awareness exception** to the Framework-First Design Principle (`.github/copilot-instructions.md` → `## Framework-First Design Principle` → "Docs-side Framework-First", LLMP-DEC-62). This single file lists which higher-layer repos consume `AyCode.Core` (Layer 0 framework). For change-impact assessment when modifying ACCORE — NOT a coupling vector.
|
||||
>
|
||||
> **Strict rule**: AyCode.Core code, types, namespaces, topic IDs, and any other `.md` files (`docs/`, `.github/` excluding the narrow workspace-meta-history exception) MUST NOT name any specific consumer listed here. **This is the SINGLE place** in ACCORE that may name consumer repos.
|
||||
|
||||
## Workspace consumer map (as of 2026-04-26)
|
||||
|
||||
| Prefix | Repo | Layer | Type | Path (workspace-relative) | Brief usage |
|
||||
|----------------|-------------------------------|------:|---------------------|--------------------------------------------------------------------|------------------------------------------------------------------------------|
|
||||
| `ACBLAZOR` | AyCode.Blazor | 1 | framework (UI) | `Aycode/Source/AyCode.Blazor` | Extends ACCORE base classes for Blazor / MAUI UI |
|
||||
| `MGNOPLIB` | Mango.Nop Libraries | 1 | framework (libs) | `Mango/Source/NopCommerce.Common/4.70/Libraries` | Domain framework for NopCommerce-plugin development |
|
||||
| `MGNOPCORE` | Mango.Nop.Core | 2 | framework (sub) | `.../Libraries/Mango.Nop.Core` | Inherit-protocol; sub-framework on top of MGNOPLIB |
|
||||
| `MGFBANKPLUG` | Nop.Plugin.Misc.AIPlugin | 3 | consumer (plugin) | `.../Plugins/Nop.Plugin.Misc.AIPlugin` | FruitBank nopCommerce plugin source |
|
||||
| `FBANKNOP` | FruitBank | 2 | product (server) | `Mango/Source/FruitBank` | nopCommerce server source for the FruitBank deployment |
|
||||
| `FBANKAPP` | FruitBankHybridApp | 2 | product (hybrid) | `Mango/Source/FruitBankHybridApp` | MAUI/Blazor hybrid client app |
|
||||
|
||||
(See `.github/REPO_PREFIXES.md` for the prefix scheme; each consumer's own `.github/copilot-instructions.md` `@repo` block declares its `prefix` value per LLMP-DEC-58.)
|
||||
|
||||
## When modifying AyCode.Core — change-impact lens
|
||||
|
||||
Use this list to assess change impact:
|
||||
- A breaking change to a base class affects all 6 consumers above (cascading rebuilds + verification).
|
||||
- A new feature gated behind opt-in DI extension → no cascade, just new capability.
|
||||
- A signature change in a widely-used interface (e.g., `IAcSignalRClientBase`) → at minimum: ACBLAZOR + MGNOPLIB + MGFBANKPLUG + FBANKNOP + FBANKAPP all need verification.
|
||||
- A change to ID format / topic-code conventions → MGNOPCORE and MGFBANKPLUG (inherit-protocol) plus all primary repos need updating.
|
||||
|
||||
**Do NOT** use this list to write framework code that conditionalizes on specific consumers. Generic abstractions only. The list is a **HEURISTIC for impact**, not an **INPUT to logic**.
|
||||
|
||||
## Maintenance
|
||||
|
||||
When a repo joins or leaves the workspace consuming AyCode.Core, update the table above. The list ITSELF is workspace-meta-tooling — not framework code domain.
|
||||
|
||||
**Future automation candidate** (filed as `ACCORE-META-T-?` in `.github/META_TODO.md`): `protocol-audit` skill could compute this list dynamically from each repo's `@repo.own-dep-repos` (inverse-graph traversal) and verify against this file — eliminating manual upkeep.
|
||||
|
||||
## Cross-references
|
||||
|
||||
- **Decision Log entries**: LLMP-DEC-62 (this file's introduction + docs-side Framework-First rule); LLMP-DEC-58 (Phase 5.1 `.github/` retightening — precedent); LLMP-DEC-25 (workspace-meta exception family).
|
||||
- **Repo prefix registry (framework's own)**: `.github/REPO_PREFIXES.md`.
|
||||
- **Topic registry (framework's own)**: `.github/skills/docs-check/references/TOPIC_CODES.md`.
|
||||
- **META TODOs / Issues**: `.github/META_TODO.md` / `.github/META_ISSUES.md`.
|
||||
Loading…
Reference in New Issue