# Local glossary

> b. review and restate the goal and intent to the user until user approves

- Skill: `tools-only/local-glossary` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/local-glossary`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/local-glossary/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/local-glossary

---

## Local glossary

- **Desired outcome**: the end state/value (what "done" means at the user/business level).
- **Objectives**: component outcomes that collectively achieve the desired outcome (often phrased as "the system/user can...").
- **Acceptance criteria**: testable statements proving each objective is met (observable, verifiable, pass/fail).
- **Skill**: a structured, in-band process wrapper (system-prompt-like structure) that drives the conversation and dispatches work.
- **Skill(fork)**: a forked subprocess skill (isolated context) that performs work and returns a structured summary + artifacts back to the main conversation.

Draft Intended workflow:

1. Skill: Discovery of desired outcome and objectives (user provided a feature, issue, task, enablement, structure change, documentation, pipeline and release flow, versioning, stakeholders, ... or anything else that comes in that is part of the project could be provided as the input and this should be treated in a flexible manner)

   NOTE: By "goal" in earlier conversation, I mean the combination of:

   - Desired outcome (end state/value)
   - Objectives (component outcomes)
   - Acceptance criteria (verification)

   A common structure is:

   - Desired outcome → 1..N objectives
   - Each objective → 1..N acceptance criteria (plus optional "anti-criteria" / non-goals)
     a. Primary Assistant: Context Gathering
     - conversational
     - dispatches researcher agents
       - Skill: Agent with tasks for online research
       - Skill: Agents with tasks for local repository discovery
       - Skill: Agents with git analysis tasks
       - Skill: Agents with GitHub or GitLab remote (or local filepath) repository reference gathering tasks.
       - Skill: Agents that check packages, latest version documentation for any mentioned technologies, i.e. if the user says it for gcc 10.3 then ensure the reference doc or url for gcc 10.3 has been collected as reference material. If the user says we are creating a release pipeline for GitLab, we should know what the current gitlab pipeline schema is and the available predefined variables.
     - Skill: validates findings with user asking contextual questions about if the findings and resources to ensure alignment towards intended goal
       b. review and restate the goal and intent to the user until user approves

2. Skill: Architecture/Design - Identifies what is required to achieve the desired outcome + objectives

   NOTE: Artifacts selected based on:

   - Project complexity (scope, cross-system impact, infrastructure changes)
   - Architectural role ownership (Systems/Solutions/Software perspectives)
   - Explicit user request

   COMPLEXITY ASSESSMENT:

   - **Simple**: Single-module, no external interfaces → ARCH-COMPONENT, API only
   - **Moderate**: Multi-module, internal APIs, config → add ARCH-CONTAINER, ARCH-SOFTWARE, SAD-SOLUTION
   - **Complex**: Cross-system, infrastructure, hardware → add ARCH-CONTEXT, ICD, DEPLOYMENT
   - **Firmware/Embedded**: Hardware interaction → add HAL

   --- Requirements & Scope (ALWAYS) ---
   a. Skill(fork): Project Requirements Documentation

   - Desired outcome, objectives, acceptance criteria
   - Feature scope, boundaries, stakeholders
     `ARTIFACT:PRD(SCOPE:...)`

   b. Skill(fork): Non-Functional Requirements

   - Performance, scalability, reliability, security constraints
   - Technology constraints, platform requirements
     `ARTIFACT:NFR(SCOPE:...)`

   --- Architecture Views (complexity-dependent) ---
   c. Skill(fork): Architecture Artifacts (C4 Model + arc42)
   Decides threshold for each level based on project complexity.
   Input: Discovery summary + PRD + NFR

   i. System Context Diagram (C4 L1 - Systems Architect)
   WHEN: External interfaces, integrations, system boundaries - System boundary, external actors, data flows in/out
   ROLE: Systems Architect perspective
   SOURCE: C4 Model <https://c4model.com/diagrams/system-context>
   `ARTIFACT:ARCH-CONTEXT(SCOPE:...)`

   ii. Container Diagram (C4 L2 - Solutions Architect)
   WHEN: Multi-service, technology selections, application boundaries - Applications, databases, queues, communication protocols - Technology choices per container
   ROLE: Solutions Architect perspective
   SOURCE: C4 Model <https://c4model.com/diagrams/container>
   `ARTIFACT:ARCH-CONTAINER(SCOPE:...)`

   iii. Component Diagram (C4 L3 - Software Architect)
   WHEN: Code changes (DEFAULT for most development work) - Internal components, interfaces, dependencies - Module organization and boundaries
   ROLE: Software/Firmware Architect perspective
   SOURCE: C4 Model <https://c4model.com/diagrams/component>
   `ARTIFACT:ARCH-COMPONENT(SCOPE:...)`

   --- Meta Project Infrastructure (when infra changes) ---
   d. Skill(fork): Meta Project Infrastructure Documentation
   WHEN: Infrastructure/tooling/process changes

   - Linting, packaging, CI/CD, tooling, contributing, debugging
     `ARTIFACT:MPI(CATEGORY:...)`

   --- Detailed Specifications (complexity-dependent) ---
   e. Skill(fork): Detailed Architecture Artifacts

   i. Interface Control Document (Systems Architect)
   WHEN: External system integration, hardware-software boundaries - Protocols, message formats, external API contracts - Hardware interface specifications
   ROLE: Systems Architect perspective
   `ARTIFACT:ICD(INTERFACE:...)`

   ii. API Specification (Software Architect)
   WHEN: New public interfaces, REST/RPC/GraphQL endpoints - Endpoints, request/response, data types, errors - Authentication, rate limits, versioning
   ROLE: Software Architect perspective
   FORMAT: OpenAPI, protobuf, GraphQL schema, etc.
   `ARTIFACT:API-SPEC(MODULE:...)`

   iii. Software Architecture Document (Software Architect)
   WHEN: New features, refactoring, architectural changes - Layers, design patterns, module organization - Internal component relationships
   ROLE: Software Architect perspective
   SOURCE: arc42 Section 5 - Building Block View
   `ARTIFACT:ARCH-SOFTWARE(SCOPE:...)`

   iv. Module Design Document (Software Architect)
   WHEN: Complex modules requiring detailed internal design - Data structures, algorithms, state machines - Error handling, concurrency, resource management
   ROLE: Software Architect perspective
   `ARTIFACT:MODULE-DESIGN(MODULE:...)`

   v. Hardware Abstraction Layer Specification (Firmware Architect)
   WHEN: Firmware/hardware interaction, embedded systems - Register definitions, driver APIs, hardware initialization - Platform-specific abstractions
   ROLE: Firmware Architect perspective
   `ARTIFACT:HAL-SPEC(HARDWARE:...)`

   vi. Deployment View (Systems Architect)
   WHEN: Infrastructure changes, new deployments, scaling - Infrastructure topology, scaling, failover - Software-to-hardware mapping
   ROLE: Systems Architect perspective
   SOURCE: arc42 Section 7, C4 Deployment Diagram
   `ARTIFACT:DEPLOYMENT(SCOPE:...)`

   vii. Solution Architecture Document (Solutions Architect)
   WHEN: Moderate-complex projects, integration patterns - Business capabilities mapped to technical components - Integration patterns, technology stack rationale
   ROLE: Solutions Architect perspective
   SOURCE: arc42 Section 4 - Solution Strategy
   `ARTIFACT:SAD-SOLUTION(SCOPE:...)`

   --- Architecture Decisions (ALWAYS) ---
   f. Skill: Architecture Decision Records

   - Technology choices, pattern selections, trade-offs
   - One ADR per significant architectural decision
     SOURCE: <https://github.com/joelparkerhenderson/architecture-decision-record>
     `ARTIFACT:ADR(DECISION:...)`

   ARTIFACT SELECTION MATRIX:

   | Complexity | Always      | Add Systems Arch  | Add Solutions Arch  | Add Software Arch             | Firmware  |
   | ---------- | ----------- | ----------------- | ------------------- | ----------------------------- | --------- |
   | Simple     | a,b,c.iii,f | -                 | -                   | c.iii, e.ii                   | -         |
   | Moderate   | a,b,c.iii,f | c.i (if external) | c.ii, e.vii         | c.iii, e.ii, e.iii            | -         |
   | Complex    | a,b,c.iii,f | c.i, e.i, e.vi    | c.ii, e.vii         | c.iii, e.ii, e.iii, e.iv      | -         |
   | Firmware   | a,b,c.iii,f | c.i, e.vi         | c.ii (if multi-sys) | c.iii, e.ii, e.iii, e.iv, e.v | e.v (HAL) |

   NOTE: "d" (MPI) created/updated when project infrastructure changes, regardless of complexity.

   ARTIFACT INTERDEPENDENCIES:

   - ARTIFACT:PRD → informs all architecture artifacts
   - ARTIFACT:NFR → constrains Solutions and Systems architecture
   - ARTIFACT:ARCH-CONTEXT → defines scope for ARCH-CONTAINER
   - ARTIFACT:ARCH-CONTAINER → defines boundaries for ARCH-COMPONENT
   - ARTIFACT:ARCH-COMPONENT → drives API-SPEC and MODULE-DESIGN
   - All architecture artifacts → referenced by ADRs for decision rationale
   - All architecture artifacts → consumed by Planning Coordination (step 3)

3. Skill(fork): Planning Coordination - The plan references what has or hasn't yet been created towards the architecture documents and each phase or step in the plan has a link to what part of which document it implements. This takes the change to the architecture artifacts and organises when it can be done in the sequence of existing items within the plan, and ensures that tthe tasks that are not overlapping are done concurrently, and the tasks that are overlapping in their scope or files they touch are done sequentially, and tasks are done in a way that future tasks can benefit from the creation of items from the previous task. Such as, if one task is creating shared utility functions, it would be done before a task that may need to use those utility functions.
4. Implementation (with git worktrees)
   a. Orchestrator agent manages the creation and cleanup of worktrees, and starting the Workers concurrently or in sequence based on the plan (not agents, independant claude instances started via the cli, or sdk)
5. Verification (multi-phase)
   └─→ Input: Implementation + Original Desired Outcome request
   Agent: Verification Agent
   Phases:
   1. Correctness (DoD, acceptance criteria)
   2. Regression (existing systems unaffected)
   3. Design Compliance (follows ADRs, patterns)
   4. Quality Standards (linting, tests, CI/CD)
   5. Documentation (runbooks, API docs complete)
      Output: ARTIFACT:VERIFICATION(SCOPE:...) (e.g. verification-report.md) with issue list