From 2dab9693bbccbd74b390c8e39edbaa3ec0fe5367 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Fri, 5 Jun 2026 17:11:35 +0200 Subject: [PATCH 01/17] 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 02/17] 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 03/17] 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: From 9080e5612617eb09ebe939e8f30bc13dfd1aac63 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 17 Jun 2026 09:38:32 +0200 Subject: [PATCH 04/17] Update Go version. --- .github/workflows/build_binaries.yml | 2 +- .github/workflows/check.yml | 2 +- AGENTS.md | 2 +- README.md | 4 ++-- go.mod | 4 ++-- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/build_binaries.yml b/.github/workflows/build_binaries.yml index 1d22f7b..e0401ce 100644 --- a/.github/workflows/build_binaries.yml +++ b/.github/workflows/build_binaries.yml @@ -39,7 +39,7 @@ jobs: - name: Set Up Go Environment uses: actions/setup-go@v5 with: - go-version: '1.22.1' + go-version: '1.26.4' - name: Build embed_code.go for Windows run: GOOS=windows GOARCH=amd64 go build -trimpath -o bin/embed-code-windows.exe main.go diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 5f15d06..e7256a9 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -19,7 +19,7 @@ jobs: - name: Set Up Go Environment uses: actions/setup-go@v5 with: - go-version: '1.22.1' + go-version: '1.26.4' - name: Run linter uses: golangci/golangci-lint-action@v8 diff --git a/AGENTS.md b/AGENTS.md index 87eb031..88b2adc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,7 +31,7 @@ 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 +`embed-code-go` is a Go command-line application. It scans Markdown and HTML documents for `embed-code` instructions, resolves source fragments, renders them inside code fences, and checks whether existing snippets are up-to-date. diff --git a/README.md b/README.md index 9b6436c..f05f836 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ To run the binary, use: #### Running with Go -If you have Go installed (version `1.22.1` recommended), you can run the tool directly: +If you have Go installed (version `1.26.4` recommended), you can run the tool directly: ```bash go run ./main.go [arguments] ``` @@ -140,7 +140,7 @@ These settings have the same role as the command-line arguments. ## Installation -* Go to https://go.dev/doc/install. Our Go version is `1.22.1`, which can be checked in the [go.mod](./go.mod) file +* Go to https://go.dev/doc/install. Our Go version is `1.26.4`, which can be checked in the [go.mod](./go.mod) file * Make sure your Go installed successfully with the command ```bash go version diff --git a/go.mod b/go.mod index 637cf52..35fe01c 100644 --- a/go.mod +++ b/go.mod @@ -18,13 +18,14 @@ module embed-code/embed-code-go -go 1.22.1 +go 1.26.4 require ( github.com/bmatcuk/doublestar/v4 v4.6.1 github.com/gobwas/glob v0.2.3 github.com/onsi/ginkgo/v2 v2.20.2 github.com/onsi/gomega v1.34.2 + golang.org/x/net v0.28.0 gopkg.in/yaml.v3 v3.0.1 ) @@ -34,7 +35,6 @@ require ( github.com/google/go-cmp v0.6.0 // indirect github.com/google/pprof v0.0.0-20240827171923-fa2c70bbbfe5 // indirect github.com/stretchr/testify v1.9.0 // indirect - golang.org/x/net v0.28.0 // indirect golang.org/x/sys v0.24.0 // indirect golang.org/x/text v0.17.0 // indirect golang.org/x/tools v0.24.0 // indirect From 48e3e5f24479ea87f0261a31911972fd583418ec Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 17 Jun 2026 09:52:08 +0200 Subject: [PATCH 05/17] Improve `type` package identification in `AGENTS.md`. --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 88b2adc..5704ea8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -81,8 +81,9 @@ first function that exposes the symptom. - `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. +- `type/`: YAML-compatible string and named-path list types. The import path + segment is `type`, but the Go package identifier is `_type` because `type` is + a Go keyword. - `test/resources/`: parser, embedding, configuration, and source-code fixtures. ## Parser And Embedding Rules From 169ac8988f4aee0aa33ce33e1afb1cd289991048 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 17 Jun 2026 11:00:14 +0200 Subject: [PATCH 06/17] Add `main` application to `.gitignore`. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 4f39e70..a81fa45 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,6 @@ /out/ **/build/ coverage.out + +# Built 'main' application +main From 118a0dc5dd545efe547324e4eceb790894121113 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 17 Jun 2026 17:24:16 +0200 Subject: [PATCH 07/17] Move skills under `.agents` folder. --- {skills => .agents/skills}/go-engineer/SKILL.md | 4 ++-- .../skills}/go-engineer/agents/openai.yaml | 0 {skills => .agents/skills}/go-tester/SKILL.md | 4 ++-- .../skills}/go-tester/agents/openai.yaml | 0 {skills => .agents/skills}/review-docs/SKILL.md | 0 .../skills}/review-docs/agents/openai.yaml | 0 {skills => .agents/skills}/writer/SKILL.md | 2 +- .../skills}/writer/agents/openai.yaml | 0 AGENTS.md | 14 +++++++------- 9 files changed, 12 insertions(+), 12 deletions(-) rename {skills => .agents/skills}/go-engineer/SKILL.md (97%) rename {skills => .agents/skills}/go-engineer/agents/openai.yaml (100%) rename {skills => .agents/skills}/go-tester/SKILL.md (96%) rename {skills => .agents/skills}/go-tester/agents/openai.yaml (100%) rename {skills => .agents/skills}/review-docs/SKILL.md (100%) rename {skills => .agents/skills}/review-docs/agents/openai.yaml (100%) rename {skills => .agents/skills}/writer/SKILL.md (99%) rename {skills => .agents/skills}/writer/agents/openai.yaml (100%) diff --git a/skills/go-engineer/SKILL.md b/.agents/skills/go-engineer/SKILL.md similarity index 97% rename from skills/go-engineer/SKILL.md rename to .agents/skills/go-engineer/SKILL.md index dbc3423..2c0f8f0 100644 --- a/skills/go-engineer/SKILL.md +++ b/.agents/skills/go-engineer/SKILL.md @@ -23,8 +23,8 @@ Use `go-engineer` for implementation work in Go: - 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`. +conventions live in `.agents/skills/go-tester/SKILL.md`; documentation review +lives in `.agents/skills/review-docs/SKILL.md`. ## Fast Path for Agents diff --git a/skills/go-engineer/agents/openai.yaml b/.agents/skills/go-engineer/agents/openai.yaml similarity index 100% rename from skills/go-engineer/agents/openai.yaml rename to .agents/skills/go-engineer/agents/openai.yaml diff --git a/skills/go-tester/SKILL.md b/.agents/skills/go-tester/SKILL.md similarity index 96% rename from skills/go-tester/SKILL.md rename to .agents/skills/go-tester/SKILL.md index 3561cd7..824fde6 100644 --- a/skills/go-tester/SKILL.md +++ b/.agents/skills/go-tester/SKILL.md @@ -17,8 +17,8 @@ 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 +- `.agents/skills/go-engineer/SKILL.md` - Go implementation policy and production code correctness. +- `.agents/skills/review-docs/SKILL.md` - documentation review for test fixtures and Markdown docs when prose changes are part of the task. ## Core Policy diff --git a/skills/go-tester/agents/openai.yaml b/.agents/skills/go-tester/agents/openai.yaml similarity index 100% rename from skills/go-tester/agents/openai.yaml rename to .agents/skills/go-tester/agents/openai.yaml diff --git a/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md similarity index 100% rename from skills/review-docs/SKILL.md rename to .agents/skills/review-docs/SKILL.md diff --git a/skills/review-docs/agents/openai.yaml b/.agents/skills/review-docs/agents/openai.yaml similarity index 100% rename from skills/review-docs/agents/openai.yaml rename to .agents/skills/review-docs/agents/openai.yaml diff --git a/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md similarity index 99% rename from skills/writer/SKILL.md rename to .agents/skills/writer/SKILL.md index c583361..24cf325 100644 --- a/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -27,7 +27,7 @@ description: > - 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`. + `.agents/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. diff --git a/skills/writer/agents/openai.yaml b/.agents/skills/writer/agents/openai.yaml similarity index 100% rename from skills/writer/agents/openai.yaml rename to .agents/skills/writer/agents/openai.yaml diff --git a/AGENTS.md b/AGENTS.md index 5704ea8..a6c6c2f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,16 +15,16 @@ live, and which local skill owns the detailed working rules. ## Skills -- `skills/go-engineer/SKILL.md`: Go implementation, debugging, refactoring, +- `.agents/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 +- `.agents/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 +- `.agents/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, +- `.agents/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. @@ -117,9 +117,9 @@ first function that exposes the symptom. 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. +- `.agents/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 From d4111a89edfbc41b9c94bf320d2f7d4a5df9e1d6 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 10:50:27 +0200 Subject: [PATCH 08/17] Update GO version in workflows. --- .github/workflows/build_binaries.yml | 2 +- .github/workflows/check.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build_binaries.yml b/.github/workflows/build_binaries.yml index e0401ce..dbe667f 100644 --- a/.github/workflows/build_binaries.yml +++ b/.github/workflows/build_binaries.yml @@ -39,7 +39,7 @@ jobs: - name: Set Up Go Environment uses: actions/setup-go@v5 with: - go-version: '1.26.4' + go-version-file: 'go.mod' - name: Build embed_code.go for Windows run: GOOS=windows GOARCH=amd64 go build -trimpath -o bin/embed-code-windows.exe main.go diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index e7256a9..0a40bf3 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -19,7 +19,7 @@ jobs: - name: Set Up Go Environment uses: actions/setup-go@v5 with: - go-version: '1.26.4' + go-version-file: 'go.mod' - name: Run linter uses: golangci/golangci-lint-action@v8 From b5821fc72fb51fecaaef8180cc20c2ea9832bc1a Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 11:08:02 +0200 Subject: [PATCH 09/17] Remove `Skills` section from AGENTS.md. --- .agents/skills/review-docs/SKILL.md | 4 ++-- .agents/skills/writer/SKILL.md | 3 +-- AGENTS.md | 32 ++++++++--------------------- 3 files changed, 11 insertions(+), 28 deletions(-) diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md index a6fe13d..381067c 100644 --- a/.agents/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -61,8 +61,8 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, - **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. + `EMBEDDING.md` owns embedding syntax, and `AGENTS.md` owns the project map + and repository-wide rules. ### C. Embedding-Specific Documentation diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md index 24cf325..f36782d 100644 --- a/.agents/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -24,8 +24,7 @@ description: > - 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 project flow, package ownership, and repository-wide rules in `AGENTS.md`. - Put language, testing, writing, and review procedures in the relevant `.agents/skills//SKILL.md`. - Put API or helper behavior that belongs with code in Go doc comments. diff --git a/AGENTS.md b/AGENTS.md index a6c6c2f..a2a8325 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,34 +1,18 @@ # Agent Instructions -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. +These instructions apply to the whole repository. Keep this file focused on the +project map, ownership boundaries, and repository-wide rules. ## Operating Policy -- Read this file and the relevant skill before changing the workspace. +- Read this file before changing the workspace. Always use matching + automatically discovered skills when they are available. - 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 - -- `.agents/skills/go-engineer/SKILL.md`: Go implementation, debugging, refactoring, - parser and embedding behavior, error handling, formatting, vetting, and - build verification. -- `.agents/skills/go-tester/SKILL.md`: Go test authoring and test review, including - Ginkgo/Gomega style, fixtures, package-level test ownership, and test command - selection. -- `.agents/skills/writer/SKILL.md`: documentation authoring and editing for - `README.md`, `EMBEDDING.md`, `AGENTS.md`, skills, Markdown fixtures, and Go - doc comments. -- `.agents/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 command-line application. It scans Markdown and @@ -111,14 +95,14 @@ first function that exposes the symptom. ## Documentation Ownership -- `AGENTS.md`: project map, processing flow, package ownership, skill routing, - and repository-level invariants. +- `AGENTS.md`: project map, processing flow, package ownership, and + repository-wide rules. - `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. -- `.agents/skills/`: operational rules for agents. Keep language-specific, - testing, and documentation authoring/review policy in the relevant skill +- `.agents/skills/`: detailed operational rules for agents. Keep + language-specific, testing, and documentation authoring/review policy there rather than duplicating it here. ## Repository Hygiene From bbac43baaa0479f35e69d59356810d18e8bd490a Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 11:25:17 +0200 Subject: [PATCH 10/17] Extract `PROJECT.md`. --- .agents/skills/review-docs/SKILL.md | 7 +- .agents/skills/writer/SKILL.md | 10 +-- AGENTS.md | 103 +++------------------------- PROJECT.md | 97 ++++++++++++++++++++++++++ 4 files changed, 116 insertions(+), 101 deletions(-) create mode 100644 PROJECT.md diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md index 381067c..89ced81 100644 --- a/.agents/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -61,8 +61,8 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, - **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 the project map - and repository-wide rules. + `EMBEDDING.md` owns embedding syntax, `PROJECT.md` owns the project map, and + `AGENTS.md` owns repository-wide agent policy. ### C. Embedding-Specific Documentation @@ -85,7 +85,8 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, 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`. + documentation review policy in `review-docs`, and the project map in + `PROJECT.md` only. - **No task-plan references.** Skills should point at durable files and source paths, not temporary task plans. diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md index f36782d..3345070 100644 --- a/.agents/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -24,17 +24,19 @@ description: > - 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, and repository-wide rules in `AGENTS.md`. +- Put project flow, package ownership, architecture boundaries, and the + documentation map in `PROJECT.md`. +- Put agent operating policy and repository-wide rules in `AGENTS.md`. - Put language, testing, writing, and review procedures in the relevant - `.agents/skills//SKILL.md`. + skill under `.agents/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 CLI flags and modes, check `main.go`, `cli/cli.go`, and the + `cli/cli_validation.go` file. - For YAML configuration, check `cli/`, `configuration/`, and config fixtures under `test/resources/config_files/`. - For embedding syntax, check `embedding/parsing/`, `embedding/processor.go`, diff --git a/AGENTS.md b/AGENTS.md index a2a8325..515a941 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,109 +1,24 @@ # Agent Instructions -These instructions apply to the whole repository. Keep this file focused on the -project map, ownership boundaries, and repository-wide rules. +These instructions apply to the whole repository. Keep this file focused on +agent operating policy and repository-wide rules. ## Operating Policy -- Read this file before changing the workspace. Always use matching - automatically discovered skills when they are available. +- Read this file before changing the workspace. +- Read [PROJECT.md](PROJECT.md) for architecture, processing flow, package + ownership, parser and embedding rules, and documentation ownership. +- Always use matching automatically discovered skills when they are available. - 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. -## Project Overview +## Project Reference -`embed-code-go` is a Go command-line application. It scans Markdown and -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, -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. The import path - segment is `type`, but the Go package identifier is `_type` because `type` is - a Go keyword. -- `test/resources/`: parser, embedding, configuration, and source-code fixtures. - -## 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 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 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 should identify every stale document it can safely - inspect. - -## Documentation Ownership - -- `AGENTS.md`: project map, processing flow, package ownership, and - repository-wide rules. -- `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. -- `.agents/skills/`: detailed operational rules for agents. Keep - language-specific, testing, and documentation authoring/review policy there - rather than duplicating it here. +See [PROJECT.md](PROJECT.md) for the project architecture, package ownership, +processing flow, parser and embedding rules, and documentation map. ## Repository Hygiene diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..3453b30 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,97 @@ +# Project Reference + +This document owns durable project knowledge for agents and contributors. For +agent operating policy, read [AGENTS.md](AGENTS.md). For user-facing usage, read +[README.md](README.md) and [EMBEDDING.md](EMBEDDING.md). + +## Overview + +`embed-code-go` is a Go command-line application. It scans Markdown and HTML +documents for `embed-code` instructions, resolves source fragments, renders +them inside code fences, and checks whether existing snippets are up-to-date. + +## Architecture Boundaries + +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 runtime config conversion. +- `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 comment-retention filtering. +- `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. The import path + segment is `type`, but the Go package identifier is `_type` because `type` is + a Go keyword. +- `test/resources/`: parser, embedding, configuration, and source-code fixtures. + +## 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 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 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 should identify every stale document it can safely + inspect before reporting. + +## Documentation Map + +- `AGENTS.md`: agent operating policy and repository-wide rules. +- `PROJECT.md`: project architecture, processing flow, package ownership, + parser and embedding rules, and documentation ownership. +- `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. +- `.agents/skills/`: detailed operational rules for agents. Keep + language-specific, testing, and documentation authoring/review policy there + rather than duplicating it here. From 657a0ab9cda8a9db448118da9deefddeceaa2bb5 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 12:47:46 +0200 Subject: [PATCH 11/17] Extract `Processing Flow` to engineering skills. --- .agents/skills/go-engineer/SKILL.md | 30 +++++++++++-- .agents/skills/review-docs/SKILL.md | 17 +++---- .agents/skills/writer/SKILL.md | 11 ++--- AGENTS.md | 8 ++-- PROJECT.md | 69 ++++------------------------- 5 files changed, 54 insertions(+), 81 deletions(-) diff --git a/.agents/skills/go-engineer/SKILL.md b/.agents/skills/go-engineer/SKILL.md index 2c0f8f0..6c988d6 100644 --- a/.agents/skills/go-engineer/SKILL.md +++ b/.agents/skills/go-engineer/SKILL.md @@ -28,12 +28,11 @@ lives in `.agents/skills/review-docs/SKILL.md`. ## Fast Path for Agents -1. Read `AGENTS.md` and the relevant implementation files in full. +1. Read `AGENTS.md`, `PROJECT.md`, and relevant implementation files. 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. +4. Defer test structure and fixtures to `go-tester` for test changes. 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. @@ -52,6 +51,27 @@ Run this before non-trivial Go changes or when the package baseline is unclear: `go test ./...`, and `go build -trimpath main.go` when integration or CLI behavior changes. +## 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. + ## MUST DO - **Preserve package ownership.** Keep process orchestration in `main.go`, @@ -102,7 +122,11 @@ Run this before non-trivial Go changes or when the package baseline is unclear: state, and `embedding/processor.go` together. - Preserve self-closing, paired, and multiline instruction forms. - Keep ordinary Markdown fences separate from embedding fences. +- Preserve the opening fence's marker length and indentation when recognizing + the closing fence and rendering source lines. - Report malformed instructions at their start line with a concrete reason. +- Prefer concrete parse reasons: missing tag end, missing closing tag, invalid + XML, missing code fence, or unclosed code fence. - Do not consume unrelated later content to recover from invalid XML. ### Embedding And Check Modes diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md index 89ced81..0e91830 100644 --- a/.agents/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -2,10 +2,11 @@ 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. + comments, README.md, EMBEDDING.md, PROJECT.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) @@ -61,8 +62,8 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, - **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, `PROJECT.md` owns the project map, and - `AGENTS.md` owns repository-wide agent policy. + `EMBEDDING.md` owns embedding syntax, `PROJECT.md` owns project description + and map, skills own implementation details, and `AGENTS.md` owns agent policy. ### C. Embedding-Specific Documentation @@ -85,8 +86,8 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, 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 the project map in - `PROJECT.md` only. + documentation review policy in `review-docs`, project description in + `PROJECT.md`, and implementation guidance in the relevant skill. - **No task-plan references.** Skills should point at durable files and source paths, not temporary task plans. diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md index 3345070..7354c37 100644 --- a/.agents/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -2,9 +2,9 @@ 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 + to create or update README.md, EMBEDDING.md, PROJECT.md, AGENTS.md, skills, + Markdown fixtures, contributor notes, examples, command snippets, Go doc + comments, or inline explanatory comments. Verifies claims against current Go code, tests, fixtures, and project flows. --- @@ -24,8 +24,9 @@ description: > - 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, architecture boundaries, and the - documentation map in `PROJECT.md`. +- Put project overview, project map, and the documentation map in `PROJECT.md`. +- Put project flow and implementation constraints in the relevant + `.agents/skills//SKILL.md` file. - Put agent operating policy and repository-wide rules in `AGENTS.md`. - Put language, testing, writing, and review procedures in the relevant skill under `.agents/skills//SKILL.md`. diff --git a/AGENTS.md b/AGENTS.md index 515a941..d501a93 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,8 @@ agent operating policy and repository-wide rules. ## Operating Policy - Read this file before changing the workspace. -- Read [PROJECT.md](PROJECT.md) for architecture, processing flow, package - ownership, parser and embedding rules, and documentation ownership. +- Read [PROJECT.md](PROJECT.md) for the project overview, project map, and + documentation map. - Always use matching automatically discovered skills when they are available. - Ask clarifying questions before implementation, review, or documentation work when scope, acceptance criteria, or constraints are not explicit. @@ -17,8 +17,8 @@ agent operating policy and repository-wide rules. ## Project Reference -See [PROJECT.md](PROJECT.md) for the project architecture, package ownership, -processing flow, parser and embedding rules, and documentation map. +See [PROJECT.md](PROJECT.md) for the project overview, project map, and +documentation map. Implementation details live in the task-specific skills. ## Repository Hygiene diff --git a/PROJECT.md b/PROJECT.md index 3453b30..db7edc4 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -1,8 +1,8 @@ -# Project Reference +# Project -This document owns durable project knowledge for agents and contributors. For -agent operating policy, read [AGENTS.md](AGENTS.md). For user-facing usage, read -[README.md](README.md) and [EMBEDDING.md](EMBEDDING.md). +This document describes what `embed-code-go` is and where its project +information lives. For agent operating policy, read [AGENTS.md](AGENTS.md). For +implementation details, use the matching discovered skill. ## Overview @@ -10,35 +10,7 @@ agent operating policy, read [AGENTS.md](AGENTS.md). For user-facing usage, read documents for `embed-code` instructions, resolves source fragments, renders them inside code fences, and checks whether existing snippets are up-to-date. -## Architecture Boundaries - -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 +## Project Map - `main.go`: executable entry point, mode dispatch, aggregate errors, and final user-facing output. @@ -60,38 +32,13 @@ first function that exposes the symptom. a Go keyword. - `test/resources/`: parser, embedding, configuration, and source-code fixtures. -## 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 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 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 should identify every stale document it can safely - inspect before reporting. - ## Documentation Map - `AGENTS.md`: agent operating policy and repository-wide rules. -- `PROJECT.md`: project architecture, processing flow, package ownership, - parser and embedding rules, and documentation ownership. +- `PROJECT.md`: project overview, project map, and documentation ownership. - `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. -- `.agents/skills/`: detailed operational rules for agents. Keep - language-specific, testing, and documentation authoring/review policy there - rather than duplicating it here. +- `.agents/skills/`: detailed operational rules for agents, including language, + testing, implementation, and documentation policy. From 7a62893294a7057bc39988fc325f0a00fec84efb Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 13:19:50 +0200 Subject: [PATCH 12/17] Improve cost-efficiency for AI agents. --- .agents/skills/review-docs/SKILL.md | 5 +++-- .agents/skills/writer/SKILL.md | 2 +- AGENTS.md | 7 +++---- PROJECT.md | 13 ++++--------- 4 files changed, 11 insertions(+), 16 deletions(-) diff --git a/.agents/skills/review-docs/SKILL.md b/.agents/skills/review-docs/SKILL.md index 0e91830..3f56541 100644 --- a/.agents/skills/review-docs/SKILL.md +++ b/.agents/skills/review-docs/SKILL.md @@ -62,8 +62,9 @@ and repository guidance. Do not duplicate `writer` for authoring strategy, - **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, `PROJECT.md` owns project description - and map, skills own implementation details, and `AGENTS.md` owns agent policy. + `EMBEDDING.md` owns embedding syntax, `PROJECT.md` owns project description, + map, and compact doc pointers, skills own implementation details, and + `AGENTS.md` owns agent policy. ### C. Embedding-Specific Documentation diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md index 7354c37..1343964 100644 --- a/.agents/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -24,7 +24,7 @@ description: > - 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 overview, project map, and the documentation map in `PROJECT.md`. +- Put `PROJECT.md` project overview, project map, and compact doc pointers. - Put project flow and implementation constraints in the relevant `.agents/skills//SKILL.md` file. - Put agent operating policy and repository-wide rules in `AGENTS.md`. diff --git a/AGENTS.md b/AGENTS.md index d501a93..c8c040e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,8 +6,7 @@ agent operating policy and repository-wide rules. ## Operating Policy - Read this file before changing the workspace. -- Read [PROJECT.md](PROJECT.md) for the project overview, project map, and - documentation map. +- Read [PROJECT.md](PROJECT.md) for the project overview and project map. - Always use matching automatically discovered skills when they are available. - Ask clarifying questions before implementation, review, or documentation work when scope, acceptance criteria, or constraints are not explicit. @@ -17,8 +16,8 @@ agent operating policy and repository-wide rules. ## Project Reference -See [PROJECT.md](PROJECT.md) for the project overview, project map, and -documentation map. Implementation details live in the task-specific skills. +See [PROJECT.md](PROJECT.md) for the project overview and project map. +Implementation details live in the matching discovered skills. ## Repository Hygiene diff --git a/PROJECT.md b/PROJECT.md index db7edc4..c90bf26 100644 --- a/PROJECT.md +++ b/PROJECT.md @@ -32,13 +32,8 @@ them inside code fences, and checks whether existing snippets are up-to-date. a Go keyword. - `test/resources/`: parser, embedding, configuration, and source-code fixtures. -## Documentation Map +## Documentation -- `AGENTS.md`: agent operating policy and repository-wide rules. -- `PROJECT.md`: project overview, project map, and documentation ownership. -- `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. -- `.agents/skills/`: detailed operational rules for agents, including language, - testing, implementation, and documentation policy. +Read `README.md` for user-facing usage, `EMBEDDING.md` for embedding syntax, +and `.agents/skills/` for task-specific implementation, testing, writing, and +review rules. From 57d0408a310262065a2b32bf082d41e683601f5e Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 13:29:44 +0200 Subject: [PATCH 13/17] Improve readability. --- .agents/skills/writer/SKILL.md | 2 +- AGENTS.md | 5 ----- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md index 1343964..79aabaa 100644 --- a/.agents/skills/writer/SKILL.md +++ b/.agents/skills/writer/SKILL.md @@ -8,7 +8,7 @@ description: > code, tests, fixtures, and project flows. --- -# Write documentation (repo-specific) +# Write documentation ## Decide the Target and Audience diff --git a/AGENTS.md b/AGENTS.md index c8c040e..322e8ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,11 +14,6 @@ agent operating policy and repository-wide rules. history in this repository. - Preserve unrelated local changes. Treat them as user work. -## Project Reference - -See [PROJECT.md](PROJECT.md) for the project overview and project map. -Implementation details live in the matching discovered skills. - ## Repository Hygiene - Do not revert unrelated user changes. From 020a2194963376068cf8be19af0077c96e4d2556 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Thu, 18 Jun 2026 14:16:04 +0200 Subject: [PATCH 14/17] Update Go version in audit. --- .agents/tasks/embed-code-go-audit.html | 2 +- .agents/tasks/embed-code-go-audit.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/tasks/embed-code-go-audit.html b/.agents/tasks/embed-code-go-audit.html index 1039f46..7286036 100644 --- a/.agents/tasks/embed-code-go-audit.html +++ b/.agents/tasks/embed-code-go-audit.html @@ -142,7 +142,7 @@

2. Executive summary

3. Repo map

Purpose. A CLI that (a) embeds named code fragments / pattern-matched line ranges from source files into <embed-code …> tags in Markdown, or (b) checks that already-embedded snippets are up-to-date. Built for TeamDev/SpineEventEngine's Hugo documentation sites (README.md:6-8).

-

Stack & maturity. Go 1.22.1 (go.mod:21), version 1.2.2 (main.go:33). 38 Go files, ~7,856 lines (~5,400 non-test). Dependencies: doublestar (globbing), gobwas/glob (patterns), yaml.v3, Ginkgo/Gomega (tests). 345 commits over two years, primarily one author. Maturity: established internal product, not a prototype — and now headed for external distribution.

+

Stack & maturity. Go 1.26.4 (go.mod:21), version 1.2.2 (main.go:33). 38 Go files, ~7,856 lines (~5,400 non-test). Dependencies: doublestar (globbing), gobwas/glob (patterns), yaml.v3, Ginkgo/Gomega (tests). 345 commits over two years, primarily one author. Maturity: established internal product, not a prototype — and now headed for external distribution.

Control flow.

main.go ─ orchestration, error aggregation, exit codes
   └─ cli/ ─────────── arg + YAML parsing → Config; validation; build []Configuration
diff --git a/.agents/tasks/embed-code-go-audit.md b/.agents/tasks/embed-code-go-audit.md
index 5173e89..a932bb6 100644
--- a/.agents/tasks/embed-code-go-audit.md
+++ b/.agents/tasks/embed-code-go-audit.md
@@ -51,7 +51,7 @@ Three issues hold it back from an A. **Top 3 risks:** (1) a **confirmed runtime
 
 **Purpose.** A CLI that (a) **embeds** named code fragments / pattern-matched line ranges from source files into `` tags in Markdown, or (b) **checks** that already-embedded snippets are up-to-date. Built for TeamDev/SpineEventEngine's Hugo documentation sites (`README.md:6-8`).
 
-**Stack & maturity.** Go 1.22.1 (`go.mod:21`), version 1.2.2 (`main.go:33`). 38 Go files, ~7,856 lines (~5,400 non-test). Dependencies: `doublestar` (globbing), `gobwas/glob` (patterns), `yaml.v3`, Ginkgo/Gomega (tests). 345 commits over two years, primarily one author. **Maturity: established internal product**, not a prototype — and now headed for external distribution.
+**Stack & maturity.** Go 1.26.4 (`go.mod:21`), version 1.2.2 (`main.go:33`). 38 Go files, ~7,856 lines (~5,400 non-test). Dependencies: `doublestar` (globbing), `gobwas/glob` (patterns), `yaml.v3`, Ginkgo/Gomega (tests). 345 commits over two years, primarily one author. **Maturity: established internal product**, not a prototype — and now headed for external distribution.
 
 **Control flow.**
 ```

From ed073c49a2ad4a2fdedec58955418bba27d516fc Mon Sep 17 00:00:00 2001
From: Vladyslav Kuksiuk 
Date: Thu, 18 Jun 2026 14:30:03 +0200
Subject: [PATCH 15/17] Improve readability.

---
 .agents/skills/go-engineer/SKILL.md           |  6 ++---
 .agents/skills/go-engineer/agents/openai.yaml |  2 +-
 .agents/skills/go-tester/SKILL.md             |  3 ++-
 .agents/skills/go-tester/agents/openai.yaml   |  2 +-
 .agents/skills/review-docs/agents/openai.yaml |  2 +-
 .agents/skills/writer/SKILL.md                | 26 +++++++++----------
 .agents/skills/writer/agents/openai.yaml      |  2 +-
 AGENTS.md                                     |  3 ++-
 PROJECT.md                                    |  6 ++---
 9 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/.agents/skills/go-engineer/SKILL.md b/.agents/skills/go-engineer/SKILL.md
index 6c988d6..6735cfe 100644
--- a/.agents/skills/go-engineer/SKILL.md
+++ b/.agents/skills/go-engineer/SKILL.md
@@ -8,7 +8,7 @@ description: >
   package APIs, formatting, vetting, and build verification.
 ---
 
-# Go - policy & pitfalls
+# Go Engineering
 
 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.
@@ -35,7 +35,7 @@ lives in `.agents/skills/review-docs/SKILL.md`.
 4. Defer test structure and fixtures to `go-tester` for test changes.
 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.
+6. Follow the git-history policy in `AGENTS.md`.
 
 ## Setup Check
 
@@ -112,7 +112,7 @@ first function that exposes the symptom.
 - **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.**
+- **No local history exceptions.** Follow the git-history policy in `AGENTS.md`.
 
 ## Project Hotspots
 
diff --git a/.agents/skills/go-engineer/agents/openai.yaml b/.agents/skills/go-engineer/agents/openai.yaml
index 6da3a8c..03bf1b6 100644
--- a/.agents/skills/go-engineer/agents/openai.yaml
+++ b/.agents/skills/go-engineer/agents/openai.yaml
@@ -1,4 +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."
+  default_prompt: "Use $go-engineer after reading AGENTS.md and PROJECT.md to implement a scoped Go change in embed-code-go."
diff --git a/.agents/skills/go-tester/SKILL.md b/.agents/skills/go-tester/SKILL.md
index 824fde6..e7d3ce4 100644
--- a/.agents/skills/go-tester/SKILL.md
+++ b/.agents/skills/go-tester/SKILL.md
@@ -36,7 +36,8 @@ Two companions own neighboring concerns:
 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.**
+6. **Follow git-history policy.** Do not commit or rewrite history unless
+   `AGENTS.md` allows it.
 
 ## Workflow
 
diff --git a/.agents/skills/go-tester/agents/openai.yaml b/.agents/skills/go-tester/agents/openai.yaml
index 9785b66..70adeb2 100644
--- a/.agents/skills/go-tester/agents/openai.yaml
+++ b/.agents/skills/go-tester/agents/openai.yaml
@@ -1,4 +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."
+  default_prompt: "Use $go-tester after reading AGENTS.md and PROJECT.md to add or review tests in embed-code-go."
diff --git a/.agents/skills/review-docs/agents/openai.yaml b/.agents/skills/review-docs/agents/openai.yaml
index 0a8d256..5a7fe20 100644
--- a/.agents/skills/review-docs/agents/openai.yaml
+++ b/.agents/skills/review-docs/agents/openai.yaml
@@ -1,4 +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."
+  default_prompt: "Use $review-docs after reading AGENTS.md and PROJECT.md to review documentation changes in embed-code-go."
diff --git a/.agents/skills/writer/SKILL.md b/.agents/skills/writer/SKILL.md
index 79aabaa..9795f19 100644
--- a/.agents/skills/writer/SKILL.md
+++ b/.agents/skills/writer/SKILL.md
@@ -20,19 +20,17 @@ description: >
 
 ## 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.md` project overview, project map, and compact doc pointers.
-- Put project flow and implementation constraints in the relevant
-  `.agents/skills//SKILL.md` file.
-- Put agent operating policy and repository-wide rules in `AGENTS.md`.
-- Put language, testing, writing, and review procedures in the relevant
-  skill under `.agents/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.
+Prefer updating an existing document over creating a new one.
+
+- `README.md`: user-facing overview, setup, configuration, modes, and flags.
+- `EMBEDDING.md`: embedding syntax, source markers, patterns, fences,
+  separators, and comment modes.
+- `PROJECT.md`: project overview, project map, and compact doc pointers.
+- `AGENTS.md`: agent operating policy and repository-wide rules.
+- `.agents/skills//SKILL.md`: language, testing, writing, review, project
+  flow, and implementation constraints.
+- Go doc comments: API or helper behavior.
+- `test/resources/`: parser and embedding fixtures.
 
 ## Verify Against Project Flows
 
@@ -106,4 +104,4 @@ When writing documentation:
 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.
+Follow the git-history policy in `AGENTS.md`.
diff --git a/.agents/skills/writer/agents/openai.yaml b/.agents/skills/writer/agents/openai.yaml
index b032a82..ff1d27e 100644
--- a/.agents/skills/writer/agents/openai.yaml
+++ b/.agents/skills/writer/agents/openai.yaml
@@ -1,4 +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."
+  default_prompt: "Use $writer after reading AGENTS.md and PROJECT.md to write or update documentation in embed-code-go."
diff --git a/AGENTS.md b/AGENTS.md
index 322e8ff..7e64594 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -7,7 +7,8 @@ agent operating policy and repository-wide rules.
 
 - Read this file before changing the workspace.
 - Read [PROJECT.md](PROJECT.md) for the project overview and project map.
-- Always use matching automatically discovered skills when they are available.
+- Use matching discovered skills when they are available. Each skill's
+  frontmatter is the routing source of truth.
 - 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
diff --git a/PROJECT.md b/PROJECT.md
index c90bf26..ebbc327 100644
--- a/PROJECT.md
+++ b/PROJECT.md
@@ -1,8 +1,8 @@
 # Project
 
-This document describes what `embed-code-go` is and where its project
-information lives. For agent operating policy, read [AGENTS.md](AGENTS.md). For
-implementation details, use the matching discovered skill.
+This document gives agents and contributors the project overview and package
+map. For agent operating policy, read [AGENTS.md](AGENTS.md). For implementation
+details, use the matching discovered skill.
 
 ## Overview
 

From ce601fa38b0851c950c0bca7466d2f87914c5768 Mon Sep 17 00:00:00 2001
From: Vladyslav Kuksiuk 
Date: Thu, 18 Jun 2026 14:43:39 +0200
Subject: [PATCH 16/17] Provide skills readme.

---
 .agents/project.md       |  4 ++++
 .agents/skills/README.md | 10 ++++++++++
 PROJECT.md               |  7 ++++---
 3 files changed, 18 insertions(+), 3 deletions(-)
 create mode 100644 .agents/project.md
 create mode 100644 .agents/skills/README.md

diff --git a/.agents/project.md b/.agents/project.md
new file mode 100644
index 0000000..749cbe0
--- /dev/null
+++ b/.agents/project.md
@@ -0,0 +1,4 @@
+# Project
+
+Read [../PROJECT.md](../PROJECT.md) for the `embed-code-go` project overview,
+package map, and documentation pointers.
diff --git a/.agents/skills/README.md b/.agents/skills/README.md
new file mode 100644
index 0000000..3eef978
--- /dev/null
+++ b/.agents/skills/README.md
@@ -0,0 +1,10 @@
+# Skills
+
+This index is only a quick orientation aid. Each skill's frontmatter remains
+the routing source of truth.
+
+- `go-engineer`: Go implementation, debugging, refactoring, and behavior review.
+- `go-tester`: Go test authoring, fixture design, and test review.
+- `writer`: documentation authoring, editing, restructuring, and claim checks.
+- `review-docs`: documentation review for prose, examples, comments, and
+  agent instructions.
diff --git a/PROJECT.md b/PROJECT.md
index ebbc327..f52a40d 100644
--- a/PROJECT.md
+++ b/PROJECT.md
@@ -34,6 +34,7 @@ them inside code fences, and checks whether existing snippets are up-to-date.
 
 ## Documentation
 
-Read `README.md` for user-facing usage, `EMBEDDING.md` for embedding syntax,
-and `.agents/skills/` for task-specific implementation, testing, writing, and
-review rules.
+- `README.md`: user-facing usage.
+- `EMBEDDING.md`: embedding syntax and examples.
+- `.agents/skills/`: task-specific rules for implementation, testing, writing,
+  and review.

From 8e58399ee7131a941b203e5457f3e0682824c09c Mon Sep 17 00:00:00 2001
From: Vladyslav Kuksiuk 
Date: Thu, 18 Jun 2026 17:25:40 +0200
Subject: [PATCH 17/17] Improve Go version mentioning.

---
 README.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f05f836..64bcf3d 100644
--- a/README.md
+++ b/README.md
@@ -47,11 +47,13 @@ To run the binary, use:
 
 #### Running with Go
 
-If you have Go installed (version `1.26.4` recommended), you can run the tool directly:
+If you have Go installed, you can run the tool directly:
 ```bash
 go run ./main.go [arguments]
 ```
 
+It is better to use the same Go version as the one specified in [go.mod](./go.mod).
+
 ### Arguments
 
 The available arguments are:
@@ -140,7 +142,7 @@ These settings have the same role as the command-line arguments.
 
 ## Installation
 
-* Go to https://go.dev/doc/install. Our Go version is `1.26.4`, which can be checked in the [go.mod](./go.mod) file
+* Go to https://go.dev/doc/install.
 * Make sure your Go installed successfully with the command
     ```bash
     go version