From 2dab9693bbccbd74b390c8e39edbaa3ec0fe5367 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Fri, 5 Jun 2026 17:11:35 +0200 Subject: [PATCH 1/3] Add AGENTS.md and skills. --- AGENTS.md | 218 +++++++++++++++++++ skills/go-code-reviewer/SKILL.md | 137 ++++++++++++ skills/go-code-reviewer/agents/openai.yaml | 4 + skills/go-engineer/SKILL.md | 148 +++++++++++++ skills/go-engineer/agents/openai.yaml | 4 + skills/project-documenter/SKILL.md | 136 ++++++++++++ skills/project-documenter/agents/openai.yaml | 4 + 7 files changed, 651 insertions(+) create mode 100644 AGENTS.md create mode 100644 skills/go-code-reviewer/SKILL.md create mode 100644 skills/go-code-reviewer/agents/openai.yaml create mode 100644 skills/go-engineer/SKILL.md create mode 100644 skills/go-engineer/agents/openai.yaml create mode 100644 skills/project-documenter/SKILL.md create mode 100644 skills/project-documenter/agents/openai.yaml diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1428737 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,218 @@ +# Agent Instructions + +These instructions apply to the whole repository. They are the primary operating +contract for every agent working in `embed-code-go`. + +## Non-Negotiable Workflow + +1. Read this file and every applicable skill under `skills/` before starting. +2. Begin every new task with a clarification round. Ask questions and wait for + the answers before editing files, formatting code, running generators, + installing dependencies, or otherwise changing the workspace. +3. Read-only inspection is allowed before the clarification round only when it + is needed to ask precise questions. +4. Establish crystal-clear agreement on: + - the desired outcome and acceptance criteria; + - the files, packages, and behavior that are in scope; + - compatibility constraints and behavior that must not change; + - expected tests and documentation updates; + - any ambiguity discovered during repository inspection. +5. If requirements conflict, remain incomplete, or depend on an unconfirmed + assumption, stop and ask. Do not guess. +6. After the user confirms the scope, state the plan and the invariants that + will be preserved. Then implement, verify, and report the result. +7. Follow these rules even when a faster shortcut appears harmless. + +## Git Safety + +- Never create commits in this repository. +- Never push, tag, merge, rebase, cherry-pick, or rewrite history. +- Do not run destructive Git commands that discard local work. +- Leave completed changes in the working tree and report the changed files and + verification results to the user. +- Treat existing uncommitted changes as user work. Preserve them and work with + them when they overlap the task. + +## Skill Selection + +- Use `skills/go-engineer/SKILL.md` for Go implementation, debugging, + refactoring, API changes, and test changes. +- Use `skills/go-code-reviewer/SKILL.md` for reviews of Go code or repository + changes. A review is read-only unless the user starts a separate fix task. +- Use `skills/project-documenter/SKILL.md` for architecture mapping, + onboarding documentation, and updates to this file, `README.md`, or `EMBEDDING.md`. +- Apply more than one skill when a task crosses those boundaries. + +## Project Mission + +`embed-code-go` is a Go 1.22.1 command-line application. It scans Markdown and +HTML documents for `` instructions, resolves source fragments, +renders them inside code fences, and checks whether existing snippets are up-to-date. + +The architecture follows a one-way flow from process orchestration to document +processing and source resolution. Keep syntax recognition, source extraction, +filesystem handling, and CLI concerns within their owning packages. Do not +collapse them into a broad utility layer or introduce circular dependencies. + +## Processing Flow + +The normal execution path is: + +1. `main.go` reads arguments, configures logging, validates input, and dispatches + `embed` or `check` mode. +2. `cli/` reads flags or YAML and produces one or more normalized + `configuration.Configuration` values. +3. `embedding.EmbedAll` or `embedding.CheckUpToDate` selects documentation files + using include and exclude patterns. +4. An `embedding.Processor` processes one document at a time. +5. `embedding/parsing/` walks the document through explicit states, records each + instruction and its code fence, and preserves unrelated document content. +6. A parsed `Instruction` resolves source content through `fragmentation/`, + optional line patterns, indentation normalization, and comment filtering. +7. Embed mode writes changed documents. Check mode compares generated content + with existing content and must not modify documentation. + +When behavior changes, trace the complete path instead of patching only the +first function that exposes the symptom. + +## Package Map + +- `main.go`: executable entry point, mode dispatch, aggregate errors, and final + user-facing output. +- `cli/`: flag parsing, YAML loading, validation, and conversion to runtime + configuration. +- `configuration/`: defaults and normalized settings used by processing code. +- `embedding/`: document discovery, per-document processing, embedding writes, + and up-to-date checks. +- `embedding/parsing/`: state-machine parser for instructions, ordinary + Markdown fences, embedding fences, and rendered-content comparison. +- `embedding/commentfilter/`: language-aware filtering for comment-retention + modes. +- `fragmentation/`: whole-file, named-fragment, and line-pattern extraction; + source lookup; partition assembly; encoding checks; and caches. +- `files/`: filesystem validation and file helpers. +- `indent/`: shared indentation measurement and removal. +- `logging/`: `slog` handler, clickable file references, panic reporting, and + terminal formatting support. +- `type/`: YAML-compatible string and named-path list types. Preserve this + existing package name even though it is unusual. +- `test/resources/`: parser, embedding, configuration, and source-code fixtures. + +## Go Engineering Rules + +- Prefer small, explicit functions and the repository's existing package + boundaries over new layers or generic helpers. +- Keep the happy path clear with early returns where they reduce nesting. +- Accept interfaces where behavior is consumed and return concrete types by + default. Do not introduce an interface for a single implementation unless it + creates a real test or ownership boundary. +- Avoid global mutable state. Existing caches must remain bounded and have + explicit lifecycle behavior. +- Do not introduce concurrency unless it solves a measured problem. Document + ordering, writes, and error aggregation must remain deterministic. +- Use `filepath` for operating-system paths. Preserve cross-platform behavior + for Windows drive paths, separators, and file URLs. +- Close files and other resources promptly, and preserve meaningful close or + flush errors when they can affect correctness. +- Keep library packages free of new panics. Return errors; reserve process exit + and panic recovery for the executable boundary. + +## Errors And Logging + +- Return errors from library packages and add context at the layer that knows + the failing operation, file, pattern, or instruction line. +- Wrap underlying errors with `%w` when callers may inspect them with + `errors.Is` or `errors.As`. +- Use `%v` only when rendering terminal-facing messages that are not returned + for further inspection. +- Do not compare errors by message text when a type, sentinel, `errors.Is`, or + `errors.As` can express the contract. +- Do not both log and return the same error in lower layers. Logging belongs at + the CLI boundary or at intentional progress/warning points. +- Aggregate independent failures with `errors.Join` when continuing provides a + more complete and still actionable result. + +## Function Documentation + +- Every function and method must have a doc comment, including unexported ones. +- Exported declarations must start with the exact exported name, following Go + documentation style. +- Unexported comments should state intent in one concise sentence and start + with the function name when natural. +- Document non-obvious side effects, filesystem writes, state transitions, + errors, and panic behavior. +- Do not narrate obvious assignments or restate the signature. + +## Parser And Embedding Invariants + +- The parser is a state machine. Inspect `embedding/parsing/constants.go`, + `state.go`, `context.go`, and the affected state together before changing it. +- Preserve these instruction forms: + - `` + - `` + - multiline instructions already represented by fixtures. +- An instruction inside an unrelated Markdown code fence is ordinary content, + not an active embedding instruction. +- Preserve the opening fence's marker length and indentation when recognizing + the corresponding closing fence and rendering source lines. +- Malformed-instruction errors must point to the instruction start line, not + EOF or a later fence line. +- Prefer concrete parse reasons: missing `>`, missing closing tag, invalid XML, + missing code fence, or unclosed code fence. +- Do not scan arbitrary later document content to guess where an invalid + instruction ends. +- Embed mode may rewrite only documents whose generated content changed. +- Check mode is read-only and must identify every stale document it can safely + inspect. + +## Testing Rules + +- Use Ginkgo/Gomega `Describe` and `It` style in packages that already use it. +- Add a focused regression test near the package that owns the bug. +- Add or update fixtures under `test/resources/` for parser and end-to-end + embedding behavior. +- Parser changes should cover successful input and relevant malformed input. +- Verify both `embed` and `check` semantics when shared processing behavior + changes. +- Keep tests deterministic, cross-platform, and independent of machine-specific + absolute paths unless the output intentionally contains one. +- Prefer behavioral assertions over assertions about incidental internal state. + +## Commands + +Run commands from the repository root unless a fixture requires another +working directory. + +- Format changed Go files: `gofmt -w `. +- Run focused tests while iterating: `go test ./embedding/...` or the affected + package. +- Run static checks for Go changes: `go vet ./...`. +- Run the full suite before finishing: `go test ./...`. +- Build the executable when CLI or integration behavior changes: + `go build -trimpath main.go`. +- Run from source: `go run ./main.go -mode ...`. + +If a required command cannot be run, report the exact reason and the remaining +risk. Do not describe unrun checks as passing. + +## Documentation Stewardship + +- Keep this file aligned with actual code. Verify package and flow descriptions + against source before editing them. +- Keep `README.md` user-oriented: installation, configuration, modes, and + common operation. +- Keep `EMBEDDING.md` focused on instruction syntax, source markers, patterns, + comment modes, and examples. +- Do not duplicate long user documentation in `AGENTS.md`; link to the owning + document and retain only the engineering invariant here. +- When architecture changes, update this package map and processing flow in the + same task after the user confirms documentation is in scope. + +## Repository Hygiene + +- Do not revert unrelated user changes. +- Do not edit generated binaries under `bin/` unless explicitly requested. +- Do not add temporary repro files, local binaries, IDE metadata, coverage + output, or build artifacts to the intended change set. +- Do not update dependencies unless the confirmed task requires it. +- Keep changes narrowly scoped and make unrelated cleanup a separate task. diff --git a/skills/go-code-reviewer/SKILL.md b/skills/go-code-reviewer/SKILL.md new file mode 100644 index 0000000..b1d13e0 --- /dev/null +++ b/skills/go-code-reviewer/SKILL.md @@ -0,0 +1,137 @@ +--- +name: go-code-reviewer +description: > + Review Go and repository changes in embed-code-go for correctness, + regressions, architecture drift, parser and embedding invariants, error + handling, filesystem safety, tests, and maintainability. Use when asked to + review a diff, branch, pull request, patch, or local changes. Read-only and + findings-first; never edits files or commits changes. +--- + +# Go Code Reviewer + +Review `embed-code-go` as a senior Go maintainer. Prioritize concrete bugs, +behavioral regressions, and missing tests over stylistic preference. + +## Mandatory Clarification Gate + +1. Read `AGENTS.md` and inspect only enough metadata to frame the review. +2. Ask the user to confirm the review target, such as unstaged changes, staged + changes, a base branch, a commit range, or named files. +3. Confirm the expected behavior or acceptance criteria and whether the review + should include tests, documentation, and compatibility concerns. +4. Wait for the answers before beginning the substantive review or running + tests. If the target changes, clarify again. + +## Read-Only Boundary + +- Do not edit source, tests, fixtures, documentation, or configuration. +- Do not apply suggested fixes. +- Do not stage, commit, push, tag, merge, rebase, or rewrite history. +- Running non-mutating analysis and tests is allowed after clarification. + +## Review Procedure + +1. Establish the exact diff and list changed files. +2. Read every changed file in full, not only the hunks. +3. Read callers, callees, tests, and fixtures needed to validate behavior. +4. Trace each behavioral change through the processing flow: + `main` -> `cli`/`configuration` -> `embedding` -> + `embedding/parsing` and `fragmentation` -> write or compare. +5. Run focused tests or static checks when they can confirm or reject a + suspected issue. +6. Report only actionable findings with evidence. + +## Correctness Checklist + +### Go Semantics + +- Errors are checked, preserved, and wrapped correctly. +- Typed or sentinel errors remain inspectable through wrapping. +- No nil dereference, invalid zero-state assumption, slice or map aliasing bug, + out-of-range access, leaked resource, or ignored write/close failure. +- Public and package contracts remain compatible unless the change explicitly + intends a break. +- Interfaces and abstractions have more than speculative value. +- New concurrency has bounded lifetime, deterministic aggregation, and no data + race or document-write race. + +### Architecture + +- CLI code does not absorb parser, embedding, or fragmentation behavior. +- Parsing states recognize syntax; they do not become source resolvers. +- Fragmentation code does not rewrite documentation. +- Utilities remain narrow and package ownership stays clear. +- The change follows established names and patterns rather than adding a + parallel mechanism. + +### Parser And Embedding + +- Valid self-closing, paired, and multiline instructions still work. +- Instruction-looking text inside ordinary Markdown fences remains inert. +- State transitions cannot skip, duplicate, or consume unrelated lines. +- Opening and closing fence indentation and marker length remain compatible. +- Parse errors point to the instruction start line with a concrete reason. +- Missing or unclosed code fences produce the intended typed error. +- Embed mode writes only changed documents. +- Check mode remains read-only and reports stale documents completely. + +### Fragmentation And Filtering + +- Whole-file, named-fragment, line-pattern, and range-pattern extraction keep + their established semantics. +- Multiple partitions preserve source order and separators. +- Indentation and comment-filter behavior remain stable for supported file + types and modes. +- Source-root names, file lookup, encoding checks, and caches handle failures + without hiding the underlying cause. + +### Filesystem And Portability + +- Paths use the correct path API and remain valid on Windows, macOS, and Linux. +- Include/exclude glob behavior does not silently broaden document writes. +- Error output retains useful file and line references. +- Tests do not depend on local absolute paths, order from map iteration, or + undeclared filesystem state. + +### Tests And Documentation + +- Functional changes have focused tests in the owning package. +- Parser changes include fixtures for success and malformed input as needed. +- Shared processing changes cover both embed and check behavior. +- Every new or changed function and method has a useful doc comment. +- User-visible syntax or configuration changes update `README.md` or + `EMBEDDING.md` when documentation is in confirmed scope. + +## Severity + +- `P0`: destructive or security-critical failure with immediate broad impact. +- `P1`: definite correctness bug, data loss, unintended document write, panic, + or major compatibility regression. +- `P2`: real bug under plausible conditions, incomplete error handling, or + missing regression coverage for changed behavior. +- `P3`: maintainability or clarity issue likely to cause future mistakes but + not currently incorrect. + +Do not report a style preference unless it creates a repository rule violation +or a concrete maintenance risk. + +## Output Format + +List findings first, ordered by severity. For every finding include: + +- priority and concise title; +- file and exact line; +- the failing scenario and impact; +- why the current tests do not prevent it; +- a concrete correction or test to add. + +Then include: + +- open questions or assumptions; +- a brief summary of the reviewed change; +- tests or checks run and their results; +- residual risk if no finding was proven. + +If there are no findings, say so clearly. Do not invent issues to fill the +report. diff --git a/skills/go-code-reviewer/agents/openai.yaml b/skills/go-code-reviewer/agents/openai.yaml new file mode 100644 index 0000000..2ab5f95 --- /dev/null +++ b/skills/go-code-reviewer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Go Code Reviewer" + short_description: "Review embed-code-go changes" + default_prompt: "Use $go-code-reviewer to review Go changes in embed-code-go." diff --git a/skills/go-engineer/SKILL.md b/skills/go-engineer/SKILL.md new file mode 100644 index 0000000..9608824 --- /dev/null +++ b/skills/go-engineer/SKILL.md @@ -0,0 +1,148 @@ +--- +name: go-engineer +description: > + Implement, debug, refactor, or explain Go code in embed-code-go. Use for + changes to .go files, Go tests, CLI behavior, parser states, fragment + extraction, filesystem handling, errors, or package APIs. Enforces the + repository clarification gate, architecture boundaries, documentation rules, + focused regression tests, formatting, vetting, and full verification. +--- + +# Go Engineer + +Act as the implementation engineer for `embed-code-go`. Assume general Go +knowledge; focus on this repository's boundaries, invariants, and recurring +failure modes. + +## Mandatory Clarification Gate + +1. Read `AGENTS.md` and inspect only enough source and tests to understand the + request and formulate precise questions. +2. Ask the user questions before making any change. At minimum confirm: + - the observable result and acceptance criteria; + - the permitted packages and non-goals; + - compatibility behavior that must remain unchanged; + - expected tests and documentation updates. +3. Wait for the answers. Do not edit, format, generate, install, or execute a + mutating command while any material ambiguity remains. +4. If the user delegates a decision, state the proposed assumption and ask for + confirmation before implementation. + +This gate applies even when the requested fix appears obvious. + +## Workflow + +### 1. Build Context + +- Read the affected implementation file in full. +- Read its package tests and relevant fixtures. +- Trace callers and downstream behavior across package boundaries. +- For parser work, read `embedding/parsing/constants.go`, `state.go`, + `context.go`, the affected state, and the processor loop together. +- For fragment work, inspect `fragmentation/` resolution, partition building, + pattern matching, indentation, encoding, and cache behavior as applicable. +- Check the working tree and preserve unrelated changes. + +### 2. State The Plan + +After clarification, briefly state: + +- files expected to change; +- behavioral invariants being preserved; +- focused tests to add or update; +- verification commands to run. + +Stop and ask again if inspection invalidates an agreed assumption. + +### 3. Implement Conservatively + +- Keep `main.go` at the process boundary and business behavior in packages. +- Keep input parsing and validation in `cli/`, normalized settings in + `configuration/`, document orchestration in `embedding/`, document syntax in + `embedding/parsing/`, and source extraction in `fragmentation/`. +- Prefer explicit code and small functions over new framework-like abstractions. +- Introduce an interface only at a real consumer or test boundary. +- Preserve deterministic document order, writes, and error aggregation. +- Use operating-system-aware path handling and preserve Windows behavior. +- Avoid new panics, hidden global state, and speculative concurrency. +- Do not update dependencies unless they are part of the confirmed scope. + +### 4. Handle Errors At The Right Layer + +- Add file, pattern, instruction, or operation context where it becomes known. +- Wrap inspectable causes with `%w`. +- Use typed errors and `errors.Is` or `errors.As` for programmatic decisions. +- Aggregate independent failures with `errors.Join` when processing can safely + continue. +- Do not log and return the same failure from a library layer. +- Keep terminal formatting and process exit in `main.go` or the CLI boundary. + +### 5. Document Every Function + +- Add a concise doc comment to every new or changed function and method. +- Start exported comments with the declaration name. +- Explain state changes, writes, non-obvious constraints, errors, or panics. +- Do not add comments that merely translate the code into prose. + +### 6. Test By Ownership + +- Put a focused regression test in the package that owns the behavior. +- Follow existing Ginkgo/Gomega style. +- Use `test/resources/` fixtures for document parsing and end-to-end embedding. +- Parser changes should include valid and malformed cases when relevant. +- Shared processing changes should verify embed writes and check-mode + read-only comparison. +- Error tests should verify useful context and instruction start lines without + overfitting entire message strings when a typed error is available. + +## High-Risk Areas + +### Parser State Machine + +- Preserve valid self-closing, paired, and multiline instruction forms. +- Ignore instruction-looking text inside unrelated Markdown code fences. +- Track embedding and ordinary Markdown fences separately. +- Preserve indentation and fence marker semantics. +- Report malformed instructions at their start line. +- Do not consume unrelated later document content to recover from invalid XML. + +### Filesystem And Writes + +- Check mode must never modify documents. +- Embed mode should write only changed documents. +- Avoid partial or surprising writes on an error path. +- Keep include/exclude matching and named source-root behavior cross-platform. + +### Fragment Resolution + +- Preserve whole-file, named-fragment, exact-pattern, and range-pattern + behavior. +- Keep partition ordering and separators stable. +- Preserve indentation normalization and requested comment filtering. +- Keep caches bounded and avoid stale data crossing an operation boundary. + +## Verification + +Run the narrowest relevant checks first, then the repository checks: + +1. `gofmt -w ` +2. `go test .//...` +3. `go vet ./...` +4. `go test ./...` +5. `go build -trimpath main.go` when CLI, configuration, embedding, or package + integration behavior changed + +For user-visible CLI behavior, run a focused `go run ./main.go ...` scenario +against existing fixtures when practical. + +## Completion Report + +Report: + +- the behavior implemented; +- files changed; +- tests and checks run with results; +- assumptions confirmed by the user; +- any remaining risk or unrun verification. + +Never commit, push, tag, or rewrite Git history. diff --git a/skills/go-engineer/agents/openai.yaml b/skills/go-engineer/agents/openai.yaml new file mode 100644 index 0000000..6da3a8c --- /dev/null +++ b/skills/go-engineer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Go Engineer" + short_description: "Implement Go changes for embed-code-go" + default_prompt: "Use $go-engineer to implement a scoped Go change in embed-code-go." diff --git a/skills/project-documenter/SKILL.md b/skills/project-documenter/SKILL.md new file mode 100644 index 0000000..eae8cb8 --- /dev/null +++ b/skills/project-documenter/SKILL.md @@ -0,0 +1,136 @@ +--- +name: project-documenter +description: > + Inspect embed-code-go and create or update source-grounded architecture, + onboarding, package-map, workflow, and agent documentation. Use when asked to + explain the grand plan, map repository components, document where to look, + refresh AGENTS.md, or align README.md and EMBEDDING.md with code. Requires a + clarification round and writes documentation instead of returning only a + conversational summary. +--- + +# Project Documenter + +Document `embed-code-go` from evidence in the repository. Treat source, tests, +fixtures, and build configuration as authoritative; treat existing prose as a +hypothesis that must be checked. + +## Mandatory Clarification Gate + +1. Read `AGENTS.md` and inspect only enough repository structure to ask precise + questions. +2. Ask the user to confirm: + - the audience: contributor, maintainer, user, or agent; + - the required output files; + - the desired depth and whether diagrams are wanted; + - whether stale existing prose may be rewritten or only extended. +3. Wait for answers before editing documentation or running generators. +4. If documentation would assert an architectural intention not demonstrated by + code, ask the user instead of inventing it. + +## Required Outcome + +When this skill is invoked to document the repository, do not finish with only +a chat summary. Write or update the user-approved documentation files. + +`AGENTS.md` is the primary maintainer and agent map. Unless the user explicitly +excludes it, update it when repository-wide architecture, workflow, package +ownership, testing policy, or agent rules are being documented. + +## Evidence Collection + +After clarification: + +1. Read `go.mod`, `main.go`, `README.md`, and `EMBEDDING.md`. +2. Enumerate packages and non-test Go files. +3. Read package entry points, exported declarations, and central data types. +4. Trace the two user journeys: + - embed mode from flags/YAML to document writes; + - check mode from flags/YAML to stale-file reporting without writes. +5. Trace parser state transitions and fragment-resolution paths. +6. Read package tests and representative fixtures to discover contracts and + malformed-input behavior. +7. Inspect CI workflows and documented build commands. +8. Check the working tree so user changes are preserved. + +Use searches and symbol lists to establish coverage, then read the important +files. Do not infer the architecture from directory names alone. + +## Documentation Ownership + +### `AGENTS.md` + +Keep repository-wide engineering guidance here: + +- mandatory working protocol and Git safety; +- skill selection; +- mission and architectural direction; +- end-to-end processing flow; +- package ownership and dependency boundaries; +- parser, embedding, testing, and documentation invariants; +- canonical development commands. + +Keep it operational and concise enough to read before every task. + +### `README.md` + +Keep user-facing material here: + +- what the CLI does; +- installation and build instructions; +- modes, flags, and YAML configuration; +- ordinary examples and expected output. + +Do not place internal state-machine details here unless users need them. + +### `EMBEDDING.md` + +Keep the embedding language here: + +- supported `` forms and attributes; +- source fragment markers and line patterns; +- fences, indentation, separators, and comment modes; +- valid and invalid examples. + +### Additional Architecture Documents + +Create additional files only when the user confirms them. Prefer a small +number of durable documents over many overlapping summaries. Link to source +paths and owning documents instead of copying large sections. + +## Writing Rules + +- Describe what the code does now. Label future direction explicitly. +- Separate verified facts from inference. +- Name exact packages, files, types, and functions that orient a maintainer. +- Explain boundaries and invariants, not every helper. +- Include where to start for common changes such as CLI configuration, parser + syntax, fragment extraction, comment filtering, or error formatting. +- Avoid claims like "always" or "never" unless code, tests, or confirmed policy + supports them. +- Keep command examples executable from the repository root. +- Use ASCII unless the existing document requires another character set. + +## Consistency Checks + +Before finishing: + +- verify every referenced path exists; +- verify command names and flags against code; +- verify package descriptions against imports and callers; +- verify parser forms and errors against tests and fixtures; +- search for stale names after renames; +- review the diff for duplicated or contradictory guidance; +- run relevant tests when documentation changes depend on behavioral claims. + +## Completion Report + +Report: + +- documentation files changed; +- architecture or workflow facts added or corrected; +- source and tests used as evidence; +- any unresolved question or intentionally omitted area; +- verification performed. + +Never commit, push, tag, or rewrite Git history. diff --git a/skills/project-documenter/agents/openai.yaml b/skills/project-documenter/agents/openai.yaml new file mode 100644 index 0000000..45bd4e6 --- /dev/null +++ b/skills/project-documenter/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Project Documenter" + short_description: "Map and document embed-code-go" + default_prompt: "Use $project-documenter to update embed-code-go architecture and agent documentation." From 3e47bc6828460b4f412f734c316f047373ce9fc2 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Mon, 8 Jun 2026 11:11:38 +0200 Subject: [PATCH 2/3] Improve agents skills segregation. --- AGENTS.md | 209 +++++----------- skills/go-code-reviewer/SKILL.md | 137 ----------- skills/go-code-reviewer/agents/openai.yaml | 4 - skills/go-engineer/SKILL.md | 238 +++++++++---------- skills/go-tester/SKILL.md | 154 ++++++++++++ skills/go-tester/agents/openai.yaml | 4 + skills/project-documenter/SKILL.md | 136 ----------- skills/project-documenter/agents/openai.yaml | 4 - skills/review-docs/SKILL.md | 109 +++++++++ skills/review-docs/agents/openai.yaml | 4 + skills/writer/SKILL.md | 107 +++++++++ skills/writer/agents/openai.yaml | 4 + 12 files changed, 560 insertions(+), 550 deletions(-) delete mode 100644 skills/go-code-reviewer/SKILL.md delete mode 100644 skills/go-code-reviewer/agents/openai.yaml create mode 100644 skills/go-tester/SKILL.md create mode 100644 skills/go-tester/agents/openai.yaml delete mode 100644 skills/project-documenter/SKILL.md delete mode 100644 skills/project-documenter/agents/openai.yaml create mode 100644 skills/review-docs/SKILL.md create mode 100644 skills/review-docs/agents/openai.yaml create mode 100644 skills/writer/SKILL.md create mode 100644 skills/writer/agents/openai.yaml diff --git a/AGENTS.md b/AGENTS.md index 1428737..b9737dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,53 +1,40 @@ # Agent Instructions -These instructions apply to the whole repository. They are the primary operating -contract for every agent working in `embed-code-go`. - -## Non-Negotiable Workflow - -1. Read this file and every applicable skill under `skills/` before starting. -2. Begin every new task with a clarification round. Ask questions and wait for - the answers before editing files, formatting code, running generators, - installing dependencies, or otherwise changing the workspace. -3. Read-only inspection is allowed before the clarification round only when it - is needed to ask precise questions. -4. Establish crystal-clear agreement on: - - the desired outcome and acceptance criteria; - - the files, packages, and behavior that are in scope; - - compatibility constraints and behavior that must not change; - - expected tests and documentation updates; - - any ambiguity discovered during repository inspection. -5. If requirements conflict, remain incomplete, or depend on an unconfirmed - assumption, stop and ask. Do not guess. -6. After the user confirms the scope, state the plan and the invariants that - will be preserved. Then implement, verify, and report the result. -7. Follow these rules even when a faster shortcut appears harmless. - -## Git Safety - -- Never create commits in this repository. -- Never push, tag, merge, rebase, cherry-pick, or rewrite history. -- Do not run destructive Git commands that discard local work. -- Leave completed changes in the working tree and report the changed files and - verification results to the user. -- Treat existing uncommitted changes as user work. Preserve them and work with - them when they overlap the task. - -## Skill Selection - -- Use `skills/go-engineer/SKILL.md` for Go implementation, debugging, - refactoring, API changes, and test changes. -- Use `skills/go-code-reviewer/SKILL.md` for reviews of Go code or repository - changes. A review is read-only unless the user starts a separate fix task. -- Use `skills/project-documenter/SKILL.md` for architecture mapping, - onboarding documentation, and updates to this file, `README.md`, or `EMBEDDING.md`. -- Apply more than one skill when a task crosses those boundaries. - -## Project Mission +These instructions apply to the whole repository. Keep this file focused on +project knowledge: what `embed-code-go` is, where the major responsibilities +live, and which local skill owns the detailed working rules. + +## Operating Policy + +- Read this file and the relevant skill before changing the workspace. +- Ask clarifying questions before implementation, review, or documentation work + when scope, acceptance criteria, or constraints are not explicit. +- Never create commits, push, tag, merge, rebase, cherry-pick, or rewrite Git + history in this repository. +- Preserve unrelated local changes. Treat them as user work. + +## Skills + +- `skills/go-engineer/SKILL.md`: Go implementation, debugging, refactoring, + parser and embedding behavior, error handling, formatting, vetting, and + build verification. +- `skills/go-tester/SKILL.md`: Go test authoring and test review, including + Ginkgo/Gomega style, fixtures, package-level test ownership, and test command + selection. +- `skills/writer/SKILL.md`: documentation authoring and editing for + `README.md`, `EMBEDDING.md`, `AGENTS.md`, skills, Markdown fixtures, and Go + doc comments. +- `skills/review-docs/SKILL.md`: documentation review for Go doc comments, + Markdown, `README.md`, `EMBEDDING.md`, skills, and this file. + +Apply multiple skills when a task crosses these boundaries. + +## Project Overview `embed-code-go` is a Go 1.22.1 command-line application. It scans Markdown and -HTML documents for `` instructions, resolves source fragments, -renders them inside code fences, and checks whether existing snippets are up-to-date. +HTML documents for `embed-code` instructions, resolves source fragments, +renders them inside code fences, and checks whether existing snippets are +up-to-date. The architecture follows a one-way flow from process orchestration to document processing and source resolution. Keep syntax recognition, source extraction, @@ -98,115 +85,40 @@ first function that exposes the symptom. existing package name even though it is unusual. - `test/resources/`: parser, embedding, configuration, and source-code fixtures. -## Go Engineering Rules - -- Prefer small, explicit functions and the repository's existing package - boundaries over new layers or generic helpers. -- Keep the happy path clear with early returns where they reduce nesting. -- Accept interfaces where behavior is consumed and return concrete types by - default. Do not introduce an interface for a single implementation unless it - creates a real test or ownership boundary. -- Avoid global mutable state. Existing caches must remain bounded and have - explicit lifecycle behavior. -- Do not introduce concurrency unless it solves a measured problem. Document - ordering, writes, and error aggregation must remain deterministic. -- Use `filepath` for operating-system paths. Preserve cross-platform behavior - for Windows drive paths, separators, and file URLs. -- Close files and other resources promptly, and preserve meaningful close or - flush errors when they can affect correctness. -- Keep library packages free of new panics. Return errors; reserve process exit - and panic recovery for the executable boundary. - -## Errors And Logging - -- Return errors from library packages and add context at the layer that knows - the failing operation, file, pattern, or instruction line. -- Wrap underlying errors with `%w` when callers may inspect them with - `errors.Is` or `errors.As`. -- Use `%v` only when rendering terminal-facing messages that are not returned - for further inspection. -- Do not compare errors by message text when a type, sentinel, `errors.Is`, or - `errors.As` can express the contract. -- Do not both log and return the same error in lower layers. Logging belongs at - the CLI boundary or at intentional progress/warning points. -- Aggregate independent failures with `errors.Join` when continuing provides a - more complete and still actionable result. - -## Function Documentation - -- Every function and method must have a doc comment, including unexported ones. -- Exported declarations must start with the exact exported name, following Go - documentation style. -- Unexported comments should state intent in one concise sentence and start - with the function name when natural. -- Document non-obvious side effects, filesystem writes, state transitions, - errors, and panic behavior. -- Do not narrate obvious assignments or restate the signature. - -## Parser And Embedding Invariants - -- The parser is a state machine. Inspect `embedding/parsing/constants.go`, - `state.go`, `context.go`, and the affected state together before changing it. -- Preserve these instruction forms: - - `` - - `` - - multiline instructions already represented by fixtures. -- An instruction inside an unrelated Markdown code fence is ordinary content, - not an active embedding instruction. +## Parser And Embedding Rules + +- The parser is state-machine based. When changing parsing behavior, inspect + `embedding/parsing/constants.go`, `state.go`, `context.go`, and the relevant + state implementation together. +- Preserve the supported instruction forms: + - ``; + - ``; + - multiline instructions represented by existing fixtures. +- Instruction-looking text inside an unrelated Markdown code fence is ordinary + content, not an active embedding instruction. - Preserve the opening fence's marker length and indentation when recognizing - the corresponding closing fence and rendering source lines. -- Malformed-instruction errors must point to the instruction start line, not + the closing fence and rendering source lines. +- Malformed-instruction errors should point to the instruction start line, not EOF or a later fence line. -- Prefer concrete parse reasons: missing `>`, missing closing tag, invalid XML, - missing code fence, or unclosed code fence. +- Prefer concrete parse reasons: missing tag end, missing closing tag, invalid + XML, missing code fence, or unclosed code fence. - Do not scan arbitrary later document content to guess where an invalid instruction ends. - Embed mode may rewrite only documents whose generated content changed. -- Check mode is read-only and must identify every stale document it can safely +- Check mode is read-only and should identify every stale document it can safely inspect. -## Testing Rules - -- Use Ginkgo/Gomega `Describe` and `It` style in packages that already use it. -- Add a focused regression test near the package that owns the bug. -- Add or update fixtures under `test/resources/` for parser and end-to-end - embedding behavior. -- Parser changes should cover successful input and relevant malformed input. -- Verify both `embed` and `check` semantics when shared processing behavior - changes. -- Keep tests deterministic, cross-platform, and independent of machine-specific - absolute paths unless the output intentionally contains one. -- Prefer behavioral assertions over assertions about incidental internal state. - -## Commands - -Run commands from the repository root unless a fixture requires another -working directory. - -- Format changed Go files: `gofmt -w `. -- Run focused tests while iterating: `go test ./embedding/...` or the affected - package. -- Run static checks for Go changes: `go vet ./...`. -- Run the full suite before finishing: `go test ./...`. -- Build the executable when CLI or integration behavior changes: - `go build -trimpath main.go`. -- Run from source: `go run ./main.go -mode ...`. - -If a required command cannot be run, report the exact reason and the remaining -risk. Do not describe unrun checks as passing. - -## Documentation Stewardship - -- Keep this file aligned with actual code. Verify package and flow descriptions - against source before editing them. -- Keep `README.md` user-oriented: installation, configuration, modes, and - common operation. -- Keep `EMBEDDING.md` focused on instruction syntax, source markers, patterns, - comment modes, and examples. -- Do not duplicate long user documentation in `AGENTS.md`; link to the owning - document and retain only the engineering invariant here. -- When architecture changes, update this package map and processing flow in the - same task after the user confirms documentation is in scope. +## Documentation Ownership + +- `AGENTS.md`: project map, processing flow, package ownership, skill routing, + and repository-level invariants. +- `README.md`: user-facing overview, installation, configuration, modes, flags, + and normal operation. +- `EMBEDDING.md`: embedding syntax, source markers, patterns, fences, + separators, comment modes, and examples. +- `skills/`: operational rules for agents. Keep language-specific, testing, and + documentation authoring/review policy in the relevant skill rather than + duplicating it here. ## Repository Hygiene @@ -214,5 +126,4 @@ risk. Do not describe unrun checks as passing. - Do not edit generated binaries under `bin/` unless explicitly requested. - Do not add temporary repro files, local binaries, IDE metadata, coverage output, or build artifacts to the intended change set. -- Do not update dependencies unless the confirmed task requires it. - Keep changes narrowly scoped and make unrelated cleanup a separate task. diff --git a/skills/go-code-reviewer/SKILL.md b/skills/go-code-reviewer/SKILL.md deleted file mode 100644 index b1d13e0..0000000 --- a/skills/go-code-reviewer/SKILL.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -name: go-code-reviewer -description: > - Review Go and repository changes in embed-code-go for correctness, - regressions, architecture drift, parser and embedding invariants, error - handling, filesystem safety, tests, and maintainability. Use when asked to - review a diff, branch, pull request, patch, or local changes. Read-only and - findings-first; never edits files or commits changes. ---- - -# Go Code Reviewer - -Review `embed-code-go` as a senior Go maintainer. Prioritize concrete bugs, -behavioral regressions, and missing tests over stylistic preference. - -## Mandatory Clarification Gate - -1. Read `AGENTS.md` and inspect only enough metadata to frame the review. -2. Ask the user to confirm the review target, such as unstaged changes, staged - changes, a base branch, a commit range, or named files. -3. Confirm the expected behavior or acceptance criteria and whether the review - should include tests, documentation, and compatibility concerns. -4. Wait for the answers before beginning the substantive review or running - tests. If the target changes, clarify again. - -## Read-Only Boundary - -- Do not edit source, tests, fixtures, documentation, or configuration. -- Do not apply suggested fixes. -- Do not stage, commit, push, tag, merge, rebase, or rewrite history. -- Running non-mutating analysis and tests is allowed after clarification. - -## Review Procedure - -1. Establish the exact diff and list changed files. -2. Read every changed file in full, not only the hunks. -3. Read callers, callees, tests, and fixtures needed to validate behavior. -4. Trace each behavioral change through the processing flow: - `main` -> `cli`/`configuration` -> `embedding` -> - `embedding/parsing` and `fragmentation` -> write or compare. -5. Run focused tests or static checks when they can confirm or reject a - suspected issue. -6. Report only actionable findings with evidence. - -## Correctness Checklist - -### Go Semantics - -- Errors are checked, preserved, and wrapped correctly. -- Typed or sentinel errors remain inspectable through wrapping. -- No nil dereference, invalid zero-state assumption, slice or map aliasing bug, - out-of-range access, leaked resource, or ignored write/close failure. -- Public and package contracts remain compatible unless the change explicitly - intends a break. -- Interfaces and abstractions have more than speculative value. -- New concurrency has bounded lifetime, deterministic aggregation, and no data - race or document-write race. - -### Architecture - -- CLI code does not absorb parser, embedding, or fragmentation behavior. -- Parsing states recognize syntax; they do not become source resolvers. -- Fragmentation code does not rewrite documentation. -- Utilities remain narrow and package ownership stays clear. -- The change follows established names and patterns rather than adding a - parallel mechanism. - -### Parser And Embedding - -- Valid self-closing, paired, and multiline instructions still work. -- Instruction-looking text inside ordinary Markdown fences remains inert. -- State transitions cannot skip, duplicate, or consume unrelated lines. -- Opening and closing fence indentation and marker length remain compatible. -- Parse errors point to the instruction start line with a concrete reason. -- Missing or unclosed code fences produce the intended typed error. -- Embed mode writes only changed documents. -- Check mode remains read-only and reports stale documents completely. - -### Fragmentation And Filtering - -- Whole-file, named-fragment, line-pattern, and range-pattern extraction keep - their established semantics. -- Multiple partitions preserve source order and separators. -- Indentation and comment-filter behavior remain stable for supported file - types and modes. -- Source-root names, file lookup, encoding checks, and caches handle failures - without hiding the underlying cause. - -### Filesystem And Portability - -- Paths use the correct path API and remain valid on Windows, macOS, and Linux. -- Include/exclude glob behavior does not silently broaden document writes. -- Error output retains useful file and line references. -- Tests do not depend on local absolute paths, order from map iteration, or - undeclared filesystem state. - -### Tests And Documentation - -- Functional changes have focused tests in the owning package. -- Parser changes include fixtures for success and malformed input as needed. -- Shared processing changes cover both embed and check behavior. -- Every new or changed function and method has a useful doc comment. -- User-visible syntax or configuration changes update `README.md` or - `EMBEDDING.md` when documentation is in confirmed scope. - -## Severity - -- `P0`: destructive or security-critical failure with immediate broad impact. -- `P1`: definite correctness bug, data loss, unintended document write, panic, - or major compatibility regression. -- `P2`: real bug under plausible conditions, incomplete error handling, or - missing regression coverage for changed behavior. -- `P3`: maintainability or clarity issue likely to cause future mistakes but - not currently incorrect. - -Do not report a style preference unless it creates a repository rule violation -or a concrete maintenance risk. - -## Output Format - -List findings first, ordered by severity. For every finding include: - -- priority and concise title; -- file and exact line; -- the failing scenario and impact; -- why the current tests do not prevent it; -- a concrete correction or test to add. - -Then include: - -- open questions or assumptions; -- a brief summary of the reviewed change; -- tests or checks run and their results; -- residual risk if no finding was proven. - -If there are no findings, say so clearly. Do not invent issues to fill the -report. diff --git a/skills/go-code-reviewer/agents/openai.yaml b/skills/go-code-reviewer/agents/openai.yaml deleted file mode 100644 index 2ab5f95..0000000 --- a/skills/go-code-reviewer/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Go Code Reviewer" - short_description: "Review embed-code-go changes" - default_prompt: "Use $go-code-reviewer to review Go changes in embed-code-go." diff --git a/skills/go-engineer/SKILL.md b/skills/go-engineer/SKILL.md index 9608824..dbc3423 100644 --- a/skills/go-engineer/SKILL.md +++ b/skills/go-engineer/SKILL.md @@ -1,132 +1,129 @@ --- name: go-engineer description: > - Implement, debug, refactor, or explain Go code in embed-code-go. Use for - changes to .go files, Go tests, CLI behavior, parser states, fragment - extraction, filesystem handling, errors, or package APIs. Enforces the - repository clarification gate, architecture boundaries, documentation rules, - focused regression tests, formatting, vetting, and full verification. + Encodes the embed-code-go Go implementation policy and recurring pitfalls. + Use whenever writing, modifying, refactoring, debugging, or reviewing Go code + in this repository, especially CLI/config parsing, parser state transitions, + embedding behavior, fragmentation, filesystem handling, error reporting, + package APIs, formatting, vetting, and build verification. --- -# Go Engineer - -Act as the implementation engineer for `embed-code-go`. Assume general Go -knowledge; focus on this repository's boundaries, invariants, and recurring -failure modes. - -## Mandatory Clarification Gate - -1. Read `AGENTS.md` and inspect only enough source and tests to understand the - request and formulate precise questions. -2. Ask the user questions before making any change. At minimum confirm: - - the observable result and acceptance criteria; - - the permitted packages and non-goals; - - compatibility behavior that must remain unchanged; - - expected tests and documentation updates. -3. Wait for the answers. Do not edit, format, generate, install, or execute a - mutating command while any material ambiguity remains. -4. If the user delegates a decision, state the proposed assumption and ask for - confirmation before implementation. - -This gate applies even when the requested fix appears obvious. - -## Workflow - -### 1. Build Context - -- Read the affected implementation file in full. -- Read its package tests and relevant fixtures. -- Trace callers and downstream behavior across package boundaries. -- For parser work, read `embedding/parsing/constants.go`, `state.go`, - `context.go`, the affected state, and the processor loop together. -- For fragment work, inspect `fragmentation/` resolution, partition building, - pattern matching, indentation, encoding, and cache behavior as applicable. -- Check the working tree and preserve unrelated changes. - -### 2. State The Plan - -After clarification, briefly state: - -- files expected to change; -- behavioral invariants being preserved; -- focused tests to add or update; -- verification commands to run. - -Stop and ask again if inspection invalidates an agreed assumption. - -### 3. Implement Conservatively - -- Keep `main.go` at the process boundary and business behavior in packages. -- Keep input parsing and validation in `cli/`, normalized settings in - `configuration/`, document orchestration in `embedding/`, document syntax in - `embedding/parsing/`, and source extraction in `fragmentation/`. -- Prefer explicit code and small functions over new framework-like abstractions. -- Introduce an interface only at a real consumer or test boundary. -- Preserve deterministic document order, writes, and error aggregation. -- Use operating-system-aware path handling and preserve Windows behavior. -- Avoid new panics, hidden global state, and speculative concurrency. -- Do not update dependencies unless they are part of the confirmed scope. - -### 4. Handle Errors At The Right Layer - -- Add file, pattern, instruction, or operation context where it becomes known. -- Wrap inspectable causes with `%w`. -- Use typed errors and `errors.Is` or `errors.As` for programmatic decisions. -- Aggregate independent failures with `errors.Join` when processing can safely - continue. -- Do not log and return the same failure from a library layer. -- Keep terminal formatting and process exit in `main.go` or the CLI boundary. - -### 5. Document Every Function - -- Add a concise doc comment to every new or changed function and method. -- Start exported comments with the declaration name. -- Explain state changes, writes, non-obvious constraints, errors, or panics. -- Do not add comments that merely translate the code into prose. - -### 6. Test By Ownership - -- Put a focused regression test in the package that owns the behavior. -- Follow existing Ginkgo/Gomega style. -- Use `test/resources/` fixtures for document parsing and end-to-end embedding. -- Parser changes should include valid and malformed cases when relevant. -- Shared processing changes should verify embed writes and check-mode - read-only comparison. -- Error tests should verify useful context and instruction start lines without - overfitting entire message strings when a typed error is available. - -## High-Risk Areas +# Go - policy & pitfalls + +Baseline Go knowledge is assumed. This skill does not teach the language; it +encodes the project policy, package boundaries, and traps that recur in `embed-code-go` work. + +## When to Use + +Use `go-engineer` for implementation work in Go: + +- Writing or changing `.go` files. +- Debugging `embed` or `check` behavior. +- Refactoring package APIs or shared helpers. +- Reviewing Go code for correctness and maintainability. + +This skill is the baseline for production Go and helper code. Test-writing +conventions live in `skills/go-tester/SKILL.md`; documentation review lives in +`skills/review-docs/SKILL.md`. + +## Fast Path for Agents + +1. Read `AGENTS.md` and the relevant implementation files in full. +2. Ask clarifying questions before editing if the requested outcome, scope, + compatibility constraints, or verification target is not explicit. +3. Apply the MUST / MUST NOT rules while editing. +4. Defer test structure and fixtures to `go-tester` when adding or reviewing + tests. +5. Verify with the narrowest relevant Go test first, then the repository-level + checks listed below. +6. Do not commit, push, tag, merge, rebase, cherry-pick, or rewrite Git history. + +## Setup Check + +Run this before non-trivial Go changes or when the package baseline is unclear: + +1. **Go version** - target the version in `go.mod`. +2. **Package owner** - identify whether the behavior belongs in `cli/`, + `configuration/`, `embedding/`, `embedding/parsing/`, `fragmentation/`, or a + support package. +3. **Test owner** - identify the package test suite and fixtures that already + cover the behavior. +4. **Commands** - plan `gofmt`, focused `go test`, `go vet ./...`, full + `go test ./...`, and `go build -trimpath main.go` when integration or CLI + behavior changes. + +## MUST DO + +- **Preserve package ownership.** Keep process orchestration in `main.go`, + argument and YAML handling in `cli/`, normalized defaults in + `configuration/`, document orchestration in `embedding/`, syntax recognition + in `embedding/parsing/`, and source extraction in `fragmentation/`. +- **Trace the full flow.** For behavior changes, walk + `main` -> `cli`/`configuration` -> `embedding` -> `embedding/parsing` and + `fragmentation` -> write or compare. +- **Keep functions small and explicit.** Prefer direct code over broad helpers + unless an abstraction removes real duplication or clarifies a shared contract. +- **Document every function and method.** Add concise doc comments to new or + changed functions, including unexported ones. Exported comments start with + the declaration name. +- **Return actionable errors.** Add file, pattern, instruction, or operation + context where that context becomes known. +- **Aggregate independent failures with `errors.Join`.** Continue processing + only when doing so produces a more complete and still safe result. +- **Preserve deterministic behavior.** Document order, fragment order, + separators, writes, and reported stale files must stay stable. +- **Use OS-aware paths.** Preserve cross-platform behavior for separators, + Windows drive paths, and file URLs. +- **Format changed Go files with `gofmt`.** + +## MUST NOT DO + +- **No new panics in library packages.** Return errors; leave process exit and + panic recovery at the executable boundary. +- **No broad utility dumping ground.** Do not move parser, filesystem, + fragmentation, and CLI behavior into a catch-all helper package. +- **No single-use interface by default.** Introduce an interface only at a real + consumer, ownership, or test boundary. +- **No speculative concurrency.** This CLI is document and filesystem heavy; + add concurrency only for a measured problem with deterministic aggregation + and write safety. +- **No log-and-return in lower layers.** Return the error; log at the CLI + boundary or at intentional progress/warning points. +- **No message-string error contracts.** Prefer typed errors, sentinels, or + `errors.Is` / `errors.As`. +- **No dependency updates unless the confirmed task requires them.** +- **No commits or history-writing.** + +## Project Hotspots ### Parser State Machine -- Preserve valid self-closing, paired, and multiline instruction forms. -- Ignore instruction-looking text inside unrelated Markdown code fences. -- Track embedding and ordinary Markdown fences separately. -- Preserve indentation and fence marker semantics. -- Report malformed instructions at their start line. -- Do not consume unrelated later document content to recover from invalid XML. +- Read `embedding/parsing/constants.go`, `state.go`, `context.go`, the affected + state, and `embedding/processor.go` together. +- Preserve self-closing, paired, and multiline instruction forms. +- Keep ordinary Markdown fences separate from embedding fences. +- Report malformed instructions at their start line with a concrete reason. +- Do not consume unrelated later content to recover from invalid XML. -### Filesystem And Writes +### Embedding And Check Modes -- Check mode must never modify documents. -- Embed mode should write only changed documents. -- Avoid partial or surprising writes on an error path. -- Keep include/exclude matching and named source-root behavior cross-platform. +- Embed mode may rewrite only documents whose generated content changed. +- Check mode is read-only and reports stale documents. +- Shared processing changes should preserve both modes. -### Fragment Resolution +### Fragmentation -- Preserve whole-file, named-fragment, exact-pattern, and range-pattern - behavior. -- Keep partition ordering and separators stable. -- Preserve indentation normalization and requested comment filtering. -- Keep caches bounded and avoid stale data crossing an operation boundary. +- Preserve whole-file, named-fragment, exact-pattern, and range-pattern extraction. +- Keep partition ordering, separator rendering, indentation normalization, and + comment filtering stable. +- Keep source-root names and lookup errors actionable. ## Verification -Run the narrowest relevant checks first, then the repository checks: +Run the narrowest relevant checks first, then broaden: 1. `gofmt -w ` -2. `go test .//...` +2. `go test ./` 3. `go vet ./...` 4. `go test ./...` 5. `go build -trimpath main.go` when CLI, configuration, embedding, or package @@ -135,14 +132,15 @@ Run the narrowest relevant checks first, then the repository checks: For user-visible CLI behavior, run a focused `go run ./main.go ...` scenario against existing fixtures when practical. -## Completion Report +## Output Format -Report: +When producing code: -- the behavior implemented; -- files changed; -- tests and checks run with results; -- assumptions confirmed by the user; -- any remaining risk or unrun verification. +1. A short plan after clarification. +2. The code changes. +3. A verification checklist with command results. +4. A note about any remaining risk or unrun check. -Never commit, push, tag, or rewrite Git history. +When reviewing code: call out MUST-DO / MUST-NOT violations explicitly and +suggest the minimal fix. End with a one-line verdict: `APPROVE`, +`APPROVE WITH CHANGES`, or `REQUEST CHANGES`. diff --git a/skills/go-tester/SKILL.md b/skills/go-tester/SKILL.md new file mode 100644 index 0000000..68775f4 --- /dev/null +++ b/skills/go-tester/SKILL.md @@ -0,0 +1,154 @@ +--- +name: go-tester +description: > + The embed-code-go authority on writing and reviewing Go tests. Use when + adding, restructuring, or reviewing tests for Go production code, parser + behavior, embedding flows, fragmentation, CLI/config validation, fixtures, + malformed inputs, regression coverage, focused go test commands, or full + suite verification. go-engineer remains the baseline for Go inside test + helper code. +--- + +# Go tester + +This skill is the single source of truth for how tests are written in +`embed-code-go`. It does not decide what behavior to change; it decides how to +cover the known behavior once the cases are identified. + +Two companions own neighboring concerns: + +- `skills/go-engineer/SKILL.md` - Go implementation policy and production code correctness. +- `skills/review-docs/SKILL.md` - documentation review for test fixtures and + Markdown docs when prose changes are part of the task. + +## Core Policy + +1. **Follow existing Ginkgo/Gomega style.** Packages use `Describe` and `It` + suites with Gomega expectations. Match the surrounding package before adding + a new style. +2. **Test behavior at the owning package.** Put the focused regression test near + the package that owns the bug or feature. +3. **Use fixtures for document behavior.** Parser and embedding changes should + add or update files under `test/resources/` when source or document shape is + part of the contract. +4. **Cover both success and failure when parser behavior changes.** Malformed + instruction tests are as important as successful embedding tests. +5. **Keep tests deterministic and portable.** Avoid machine-specific absolute + paths, map iteration order, hidden local files, and OS-specific separators + unless the code intentionally emits them. +6. **Do not commit or rewrite history.** + +## Workflow + +1. **Read first.** Read the code under test, its package tests, and relevant + fixtures in full. +2. **Identify the owning suite.** Prefer extending an existing `Describe` block + over creating a parallel test structure. +3. **Choose the level.** Use package-level unit tests for pure helpers, parser + tests for state-machine behavior, and embedding tests for end-to-end + document rewrites or stale checks. +4. **Add the minimal fixture.** Create or update only the source and document + fixture needed to express the behavior. +5. **Assert behavior, not implementation trivia.** Prefer outputs, changed-file + lists, typed errors, and line numbers over private state. +6. **Run the narrowest test first.** Broaden only after the focused test passes. + +## Naming And Structure + +- Keep test files beside the package they test, using the existing `_test.go` + naming pattern. +- Match the package's current package name. Do not switch between internal and + external test packages without a reason. +- Use `Describe` for the unit or component under test and `It` for the behavior sentence. +- Keep setup close to the test unless the package already has a clear helper pattern. +- Use `BeforeEach` only when it reduces duplication without hiding essential state. +- Avoid broad helper functions that make the fixture harder to read. + +## Assertions + +- Use Gomega matchers already used by the package. +- Prefer exact content assertions for rendered snippets when formatting is the contract. +- Prefer typed error checks with `errors.As` when the code exposes a typed error. +- Verify line numbers for malformed instructions, especially when the bug is an + EOF or later-fence misreport. +- Avoid matching full error strings unless the user-facing message itself is + the behavior under test. + +## Fixture Guidance + +### Documentation Fixtures + +- Put documentation files under `test/resources/docs/`. +- Keep one behavior per fixture unless a multi-case document is already the + package convention. +- Name malformed fixtures after the malformed condition, not the expected implementation fix. +- Preserve indentation and code-fence marker details when those are part of the behavior. + +### Source Fixtures + +- Put source files under the existing language folder in `test/resources/code/`. +- Add the smallest source file or fragment marker needed for the behavior. +- Reuse existing Java, Kotlin, plain-text, or literal-pattern fixtures when + doing so keeps the test clearer. + +### Prepared Fragments + +- Use `test/resources/prepared-fragments/` only for behavior that already relies + on prepared expected content. +- Keep expected files stable and easy to diff. + +## Package-Specific Coverage + +- `cli/`: validation matrix, config-file loading, named code roots, duplicate + embedding names, include/exclude defaults, and invalid mode behavior. +- `embedding/`: document discovery, embed writes, check-mode stale files, + multi-configuration aggregation, and joined errors. +- `embedding/parsing/`: state transitions, ordinary Markdown fences, + instruction parsing, missing fences, unclosed fences, malformed XML, and + instruction start-line errors. +- `embedding/commentfilter/`: supported language modes, unsupported modes, + quoted comment delimiters, and block-comment edge cases. +- `fragmentation/`: fragment marker parsing, nested or overlapping fragments, + whole-file fallback, line and range patterns, encoding, source lookup, and + cache behavior. +- `files/`, `indent/`, `logging/`, `type/`: cross-platform edge cases, + formatting contracts, YAML unmarshalling, and small helper boundaries. + +## Verification + +Use the smallest useful command while iterating: + +- Parser changes: `go test ./embedding/parsing` +- Embedding behavior: `go test ./embedding` +- Fragment extraction: `go test ./fragmentation` +- CLI/config behavior: `go test ./cli` +- Shared or uncertain behavior: `go test ./...` + +After Go test code changes, run: + +1. `gofmt -w ` +2. the focused package test +3. `go test ./...` + +Run `go vet ./...` when the test change also changes helper code, exported +test support, or production code. + +## Repo Notes + +- Tests use the repository fixtures heavily; prefer a focused fixture over a + large inline string when document shape matters. +- Do not rely on local absolute paths except where the code intentionally emits + a `file://` reference. +- If the implementation change is still unclear, return to `go-engineer` + before writing tests. + +## Output Format + +When writing tests: + +1. State the behavior being covered. +2. List fixtures added or changed. +3. Report focused and full test commands run. + +When reviewing tests: group findings as `Must fix`, `Should fix`, and `Nits`. +End with `APPROVE`, `APPROVE WITH CHANGES`, or `REQUEST CHANGES`. diff --git a/skills/go-tester/agents/openai.yaml b/skills/go-tester/agents/openai.yaml new file mode 100644 index 0000000..9785b66 --- /dev/null +++ b/skills/go-tester/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Go Tester" + short_description: "Write embed-code-go Go tests" + default_prompt: "Use $go-tester to add or review tests in embed-code-go." diff --git a/skills/project-documenter/SKILL.md b/skills/project-documenter/SKILL.md deleted file mode 100644 index eae8cb8..0000000 --- a/skills/project-documenter/SKILL.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -name: project-documenter -description: > - Inspect embed-code-go and create or update source-grounded architecture, - onboarding, package-map, workflow, and agent documentation. Use when asked to - explain the grand plan, map repository components, document where to look, - refresh AGENTS.md, or align README.md and EMBEDDING.md with code. Requires a - clarification round and writes documentation instead of returning only a - conversational summary. ---- - -# Project Documenter - -Document `embed-code-go` from evidence in the repository. Treat source, tests, -fixtures, and build configuration as authoritative; treat existing prose as a -hypothesis that must be checked. - -## Mandatory Clarification Gate - -1. Read `AGENTS.md` and inspect only enough repository structure to ask precise - questions. -2. Ask the user to confirm: - - the audience: contributor, maintainer, user, or agent; - - the required output files; - - the desired depth and whether diagrams are wanted; - - whether stale existing prose may be rewritten or only extended. -3. Wait for answers before editing documentation or running generators. -4. If documentation would assert an architectural intention not demonstrated by - code, ask the user instead of inventing it. - -## Required Outcome - -When this skill is invoked to document the repository, do not finish with only -a chat summary. Write or update the user-approved documentation files. - -`AGENTS.md` is the primary maintainer and agent map. Unless the user explicitly -excludes it, update it when repository-wide architecture, workflow, package -ownership, testing policy, or agent rules are being documented. - -## Evidence Collection - -After clarification: - -1. Read `go.mod`, `main.go`, `README.md`, and `EMBEDDING.md`. -2. Enumerate packages and non-test Go files. -3. Read package entry points, exported declarations, and central data types. -4. Trace the two user journeys: - - embed mode from flags/YAML to document writes; - - check mode from flags/YAML to stale-file reporting without writes. -5. Trace parser state transitions and fragment-resolution paths. -6. Read package tests and representative fixtures to discover contracts and - malformed-input behavior. -7. Inspect CI workflows and documented build commands. -8. Check the working tree so user changes are preserved. - -Use searches and symbol lists to establish coverage, then read the important -files. Do not infer the architecture from directory names alone. - -## Documentation Ownership - -### `AGENTS.md` - -Keep repository-wide engineering guidance here: - -- mandatory working protocol and Git safety; -- skill selection; -- mission and architectural direction; -- end-to-end processing flow; -- package ownership and dependency boundaries; -- parser, embedding, testing, and documentation invariants; -- canonical development commands. - -Keep it operational and concise enough to read before every task. - -### `README.md` - -Keep user-facing material here: - -- what the CLI does; -- installation and build instructions; -- modes, flags, and YAML configuration; -- ordinary examples and expected output. - -Do not place internal state-machine details here unless users need them. - -### `EMBEDDING.md` - -Keep the embedding language here: - -- supported `` forms and attributes; -- source fragment markers and line patterns; -- fences, indentation, separators, and comment modes; -- valid and invalid examples. - -### Additional Architecture Documents - -Create additional files only when the user confirms them. Prefer a small -number of durable documents over many overlapping summaries. Link to source -paths and owning documents instead of copying large sections. - -## Writing Rules - -- Describe what the code does now. Label future direction explicitly. -- Separate verified facts from inference. -- Name exact packages, files, types, and functions that orient a maintainer. -- Explain boundaries and invariants, not every helper. -- Include where to start for common changes such as CLI configuration, parser - syntax, fragment extraction, comment filtering, or error formatting. -- Avoid claims like "always" or "never" unless code, tests, or confirmed policy - supports them. -- Keep command examples executable from the repository root. -- Use ASCII unless the existing document requires another character set. - -## Consistency Checks - -Before finishing: - -- verify every referenced path exists; -- verify command names and flags against code; -- verify package descriptions against imports and callers; -- verify parser forms and errors against tests and fixtures; -- search for stale names after renames; -- review the diff for duplicated or contradictory guidance; -- run relevant tests when documentation changes depend on behavioral claims. - -## Completion Report - -Report: - -- documentation files changed; -- architecture or workflow facts added or corrected; -- source and tests used as evidence; -- any unresolved question or intentionally omitted area; -- verification performed. - -Never commit, push, tag, or rewrite Git history. diff --git a/skills/project-documenter/agents/openai.yaml b/skills/project-documenter/agents/openai.yaml deleted file mode 100644 index 45bd4e6..0000000 --- a/skills/project-documenter/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Project Documenter" - short_description: "Map and document embed-code-go" - default_prompt: "Use $project-documenter to update embed-code-go architecture and agent documentation." diff --git a/skills/review-docs/SKILL.md b/skills/review-docs/SKILL.md new file mode 100644 index 0000000..a6fe13d --- /dev/null +++ b/skills/review-docs/SKILL.md @@ -0,0 +1,109 @@ +--- +name: review-docs +description: > + Reviews documentation changes in embed-code-go: Go doc comments, inline + comments, README.md, EMBEDDING.md, AGENTS.md, skills, Markdown fixtures, and + user-facing examples. Use when a diff touches prose, documentation comments, + embedding syntax docs, command examples, architecture/package maps, or agent + instructions. Read-only; does not run builds unless explicitly asked. +--- + +# Review documentation (repo-specific) + +You are the documentation reviewer for `embed-code-go`. Focus strictly on +documentation quality: Go doc comments, inline comments, Markdown, examples, +and repository guidance. Do not duplicate `writer` for authoring strategy, +`go-engineer` for implementation correctness, or `go-tester` for test design. + +## Review Procedure + +1. **Scope the diff.** Review changed documentation files and changed comments + inside Go sources. Do not review the full repository unless asked. +2. **Read each affected file fully.** Prose quality, heading hierarchy, command + accuracy, and identifier references require context beyond the diff hunk. +3. **Verify claims against source.** When documentation mentions flags, + attributes, parser behavior, package ownership, or command output, confirm it + against the relevant code or tests. +4. **Stay in scope.** If you spot a code or test issue, mention it briefly as a + handoff item for `go-engineer` or `go-tester` instead of expanding the docs review. + +## Checks + +### A. Go Doc Comments + +- **Every new or changed function and method has a doc comment.** This project + documents unexported functions too. +- **Exported comments start with the exact declaration name.** Follow standard + Go doc style for exported types, constants, variables, functions, and methods. +- **Unexported comments explain intent.** Starting with the function name is + preferred when it reads naturally. +- **Comments describe behavior, not signatures.** Avoid prose that only + restates parameters, return values, or obvious assignments. +- **Mention important effects.** Document filesystem writes, state transitions, + returned errors, panic behavior, and non-obvious parser constraints. +- **Inline comments in production code are rare.** They should explain why a + constraint exists, not narrate what the next line does. +- **Paths and identifiers are exact.** Render file paths, package paths, command + names, flags, and code identifiers in backticks. + +### B. Markdown Docs + +- **Heading hierarchy is valid.** Use one top-level `#`; do not skip heading levels. +- **Commands are fenced.** Use fenced code blocks for shell commands and file + examples. Avoid indented command blocks. +- **Examples are current.** Verify documented flags, modes, config keys, + instruction attributes, and default values against code. +- **Links resolve.** Check local relative links and referenced paths. External + inline links are acceptable when the surrounding file already uses them. +- **Terminology is consistent.** Use one term for the same concept within a + change set: embedding instruction, code fence, fragment, source root, docs + root, check mode, embed mode. +- **No orphans.** A paragraph, list item, or table cell must not end with a + final line containing only one word. Flag it and propose a reflow or rewrite. +- **Project docs keep their ownership.** `README.md` is user-facing, + `EMBEDDING.md` owns embedding syntax, and `AGENTS.md` owns project map and + skill routing. + +### C. Embedding-Specific Documentation + +- **Instruction forms match parser behavior.** Do not document unsupported syntax. +- **Malformed examples name the actual failure.** Prefer concrete reasons such + as invalid XML, missing tag end, missing closing tag, missing code fence, or + unclosed code fence. +- **Line-number claims are checked.** Parser errors should point to the + instruction start line. +- **Mode behavior is explicit.** Embed mode writes changed docs; check mode is + read-only and reports stale docs. +- **Fixtures remain readable.** Markdown fixtures under `test/resources/docs/` + should be small and named after the behavior they represent. + +### D. Skills And Agent Docs + +- **Skill frontmatter is compact and trigger-focused.** `name` is hyphen-case + and matches the directory. `description` explains when to use the skill. +- **Skill body follows the pattern.** Prefer role intro, use cases, + fast path or workflow, checks/policy sections, repo notes, and output format. +- **Avoid duplicated policy.** Keep language policy in `go-engineer`, test + policy in `go-tester`, documentation authoring policy in `writer`, + documentation review policy in `review-docs`, and project map in `AGENTS.md`. +- **No task-plan references.** Skills should point at durable files and source + paths, not temporary task plans. + +## Output Format + +Return three sections, in this order: + +- **Must fix** - broken links, documented commands or syntax that are false, + missing required doc comments on changed functions, or Markdown structure + that prevents correct rendering. +- **Should fix** - unclear comments, duplicated policy, stale package maps, + inconsistent terminology, orphaned one-word final lines, overbroad inline + comments, or examples that are technically right but likely to mislead. +- **Nits** - wording, wrapping, minor style, or handoff notes for + `go-engineer` / `go-tester`. + +For each finding, cite the file and line, quote the relevant text, explain the +impact, and show the recommended rewrite. If a section is empty, write `None.` + +End with a one-line verdict: `APPROVE`, `APPROVE WITH CHANGES`, or +`REQUEST CHANGES`. diff --git a/skills/review-docs/agents/openai.yaml b/skills/review-docs/agents/openai.yaml new file mode 100644 index 0000000..0a8d256 --- /dev/null +++ b/skills/review-docs/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Review Docs" + short_description: "Review embed-code-go documentation" + default_prompt: "Use $review-docs to review documentation changes in embed-code-go." diff --git a/skills/writer/SKILL.md b/skills/writer/SKILL.md new file mode 100644 index 0000000..c583361 --- /dev/null +++ b/skills/writer/SKILL.md @@ -0,0 +1,107 @@ +--- +name: writer +description: > + Writes, edits, and restructures embed-code-go documentation. Use when asked + to create or update README.md, EMBEDDING.md, AGENTS.md, skills, Markdown + fixtures, contributor notes, examples, command snippets, Go doc comments, or + inline explanatory comments. Verifies documentation claims against current Go + code, tests, fixtures, and project flows. +--- + +# Write documentation (repo-specific) + +## Decide the Target and Audience + +- Identify the target reader: CLI user, contributor, maintainer, or agent. +- Identify the task type: new doc, update, restructure, or documentation audit. +- Identify the acceptance criteria: what is correct when the reader is done? +- Ask clarifying questions before editing if the audience, scope, or expected + output file is unclear. + +## Choose Where The Content Should Live + +- Prefer updating an existing document over creating a new one. +- Put project entry-point and usage content in `README.md`. +- Put embedding syntax, source markers, patterns, fences, separators, comment + modes, and examples in `EMBEDDING.md`. +- Put project flow, package ownership, skill routing, and repository-level + invariants in `AGENTS.md`. +- Put language, testing, writing, and review procedures in the relevant + `skills//SKILL.md`. +- Put API or helper behavior that belongs with code in Go doc comments. +- Put parser and embedding fixtures under `test/resources/` only when they are + part of tests or examples already in scope. + +## Verify Against Project Flows + +- For CLI flags and modes, check `main.go`, `cli/cli.go`, and + `cli/cli_validation.go`. +- For YAML configuration, check `cli/`, `configuration/`, and config fixtures + under `test/resources/config_files/`. +- For embedding syntax, check `embedding/parsing/`, `embedding/processor.go`, + `embedding/parsing/instruction.go`, and `EMBEDDING.md`. +- For source fragments and patterns, check `fragmentation/`, + `embedding/parsing/pattern.go`, and relevant source fixtures. +- For comments modes, check `embedding/commentfilter/`. +- For examples that claim command output or write behavior, verify with tests or + a focused `go run ./main.go ...` command when practical. + +## Follow Local Documentation Conventions + +- Use fenced code blocks for commands, YAML, Markdown, and source examples. +- Render file paths, package paths, flags, config keys, instruction attributes, + function names, and command names as code. +- Keep headings hierarchical: one top-level `#`, then ordered levels without skips. +- Preserve the existing link style of the file being edited. Use local relative + links for repository files. Prefer reference-style links for long external + URLs when they improve readability. +- Keep examples small enough to verify and copy. +- Use consistent terminology: embed mode, check mode, embedding instruction, + code fence, fragment, source root, docs root, include pattern, exclude pattern. +- Do not leave orphans in prose: no paragraph, list item, or table cell should + end with a final line containing only one word. Reflow or rewrite the text. +- Do not duplicate long explanations between `README.md`, `EMBEDDING.md`, and + `AGENTS.md`; link to the owning document instead. + +## Go Doc Comment Guidance + +- Every new or changed function and method should have a useful doc comment in + this project, including unexported functions. +- Exported comments start with the exact declaration name. +- Unexported comments state intent and start with the function name when it + reads naturally. +- Document non-obvious state transitions, filesystem writes, returned errors, + panics, and parser constraints. +- Do not restate the signature or narrate obvious assignments. +- Inline comments in production Go should explain why a constraint exists, not + what the next line does. + +## Make Docs Actionable + +- Prefer executable steps, expected outcomes, and concrete examples over broad descriptions. +- Include prerequisites such as Go version, working directory, fixture location, + or mode when they are easy to miss. +- When documenting failure behavior, include the concrete reason and where the + user should look. +- When documenting architecture, describe ownership boundaries and the normal + flow rather than every helper function. + +## Validate Changes + +- Verify every referenced path exists. +- Verify flags, config keys, defaults, and instruction attributes against code. +- Verify Markdown examples and local links. +- Run `go test ./...` when documentation changes depend on behavior described by + tests or fixtures. +- Run a focused `go run ./main.go ...` scenario when adding or changing a CLI example. + +## Output Format + +When writing documentation: + +1. State the target audience and file location. +2. Summarize the documentation changed. +3. List source files, tests, or fixtures used to verify claims. +4. Report validation commands run and any remaining unverified claims. + +Never commit, push, tag, or rewrite Git history. diff --git a/skills/writer/agents/openai.yaml b/skills/writer/agents/openai.yaml new file mode 100644 index 0000000..b032a82 --- /dev/null +++ b/skills/writer/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Writer" + short_description: "Write embed-code-go documentation" + default_prompt: "Use $writer to write or update documentation in embed-code-go." From 9022cbe9d92e0d5685f4388f07dc750f93662cd4 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Fri, 12 Jun 2026 18:28:33 +0200 Subject: [PATCH 3/3] Remove redundant point. --- AGENTS.md | 2 +- skills/go-tester/SKILL.md | 17 ----------------- 2 files changed, 1 insertion(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b9737dd..87eb031 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,6 +124,6 @@ first function that exposes the symptom. - Do not revert unrelated user changes. - Do not edit generated binaries under `bin/` unless explicitly requested. -- Do not add temporary repro files, local binaries, IDE metadata, coverage +- Do not add temporary repo files, local binaries, IDE metadata, coverage output, or build artifacts to the intended change set. - Keep changes narrowly scoped and make unrelated cleanup a separate task. diff --git a/skills/go-tester/SKILL.md b/skills/go-tester/SKILL.md index 68775f4..3561cd7 100644 --- a/skills/go-tester/SKILL.md +++ b/skills/go-tester/SKILL.md @@ -97,23 +97,6 @@ Two companions own neighboring concerns: on prepared expected content. - Keep expected files stable and easy to diff. -## Package-Specific Coverage - -- `cli/`: validation matrix, config-file loading, named code roots, duplicate - embedding names, include/exclude defaults, and invalid mode behavior. -- `embedding/`: document discovery, embed writes, check-mode stale files, - multi-configuration aggregation, and joined errors. -- `embedding/parsing/`: state transitions, ordinary Markdown fences, - instruction parsing, missing fences, unclosed fences, malformed XML, and - instruction start-line errors. -- `embedding/commentfilter/`: supported language modes, unsupported modes, - quoted comment delimiters, and block-comment edge cases. -- `fragmentation/`: fragment marker parsing, nested or overlapping fragments, - whole-file fallback, line and range patterns, encoding, source lookup, and - cache behavior. -- `files/`, `indent/`, `logging/`, `type/`: cross-platform edge cases, - formatting contracts, YAML unmarshalling, and small helper boundaries. - ## Verification Use the smallest useful command while iterating: