Add AI agents instructions by Vladyslav-Kuksiuk · Pull Request #49 · SpineEventEngine/embed-code-go

Vladyslav-Kuksiuk · 2026-06-08T09:14:21Z

This PR adds an AGENTS.md file and a set of skills to guide AI agents when working with the embed-code-go repository.

Also this PR updates Go version to 1.26.4.

alexander-yevsyukov · 2026-06-17T00:04:17Z

+
+## Project Overview
+
+`embed-code-go` is a Go 1.22.1 command-line application. It scans Markdown and


Why would we want a precise version of Go in this context?

And, BTW, why do we stick to this version? It's pretty old one.

https://go.dev/doc/devel/release

We do not need this exact version, it was just the version originally used in the project.

I've updated it.

alexander-yevsyukov · 2026-06-17T00:04:57Z

@codex review.

alexander-yevsyukov · 2026-06-17T00:06:33Z

@Oleg-Melnik, two questions:

Why does it take 4 days to merge a PR?
Why don't you use agent reviews?

Copilot

Pull request overview

Adds repository-level guidance for AI agents working in embed-code-go, including a central AGENTS.md and new skill definitions to route agents toward the right procedures for Go implementation, testing, and documentation work.

Changes:

Introduces AGENTS.md with operating policy, project flow, package map, and documentation ownership.
Adds four agent skills (go-engineer, go-tester, writer, review-docs) with repo-specific workflows and checks.
Adds OpenAI agent interface descriptors for each new skill.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
AGENTS.md	Adds repo-wide agent policy plus architecture/package ownership map.
skills/go-engineer/SKILL.md	Defines Go implementation policy, package boundaries, and verification commands.
skills/go-engineer/agents/openai.yaml	Registers the Go Engineer skill for the agent UI.
skills/go-tester/SKILL.md	Defines Go test conventions (Ginkgo/Gomega), fixture usage, and verification workflow.
skills/go-tester/agents/openai.yaml	Registers the Go Tester skill for the agent UI.
skills/writer/SKILL.md	Defines documentation authoring rules and verification expectations tied to repo structure.
skills/writer/agents/openai.yaml	Registers the Writer skill for the agent UI.
skills/review-docs/SKILL.md	Defines documentation review procedure/checklist and required output structure.
skills/review-docs/agents/openai.yaml	Registers the Review Docs skill for the agent UI.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

alexander-yevsyukov

Please see my question regarding the version of Go under AGENTS.md.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9022cbe9d9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Oleg-Melnik · 2026-06-17T11:20:34Z

@Oleg-Melnik, two questions:

Why does it take 4 days to merge a PR?

Why don't you use agent reviews?

@alexander-yevsyukov
I'm currently working out how to do this the right way.

Oleg-Melnik

Please move agent configuration files under the .agents directory.

Copilot

Pull request overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Oleg-Melnik

LGTM with resolved comments from Copilot prior to merging.

alexander-yevsyukov

@Vladyslav-Kuksiuk, I've allocated a Copilot seat in this org. for you.
Now you should see the comments from Copilot.
Please address them before requesting my re-review.

@Oleg-Melnik, FYI.

alexander-yevsyukov · 2026-06-17T23:29:48Z

+- `.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.


Skills are automatically discovered. I don't think we should have this section at all.
If we have this section, it limits agents in the discovery of skills in the pre-defined directory.
Again, please consult with Codex or Claude about this issue.
Have Codex audit this PR and address its comments.

I've removed this section, as redundant.

alexander-yevsyukov · 2026-06-17T23:30:56Z

+
+Apply multiple skills when a task crosses these boundaries.
+
+## Project Overview


There must be a separate PROJECT.md or project.md and this file should link to it.
Ask agents for advices on structuring information about it. They are helpful if you ask smart questions.

I've created the PROJECT.md file.

alexander-yevsyukov · 2026-06-17T23:34:18Z

+filesystem handling, and CLI concerns within their owning packages. Do not
+collapse them into a broad utility layer or introduce circular dependencies.
+
+## Processing Flow


This belongs to engineering part of the docs. This file is not about it.

Please see how https://github.com/SpineEventEngine/config and https://github.com/SpineEventEngine/agents are organised.

You don't need that complex setup for one-repository show. But you can have better idea of what should be in the files like AGENTS.md and where a project description and coding rules belong.

I've moved it to the engineering skills.

alexander-yevsyukov · 2026-06-17T23:37:48Z

+- Check mode is read-only and should identify every stale document it can safely
+  inspect.
+
+## Documentation Ownership


This section may be redundant. Ask a separate agent to review this content. It may give you hints on optimisation. Ask directly, that you want economic agent guidelines that efficient on tokens. This usually helps.

I've removed this section and applied the cost-efficiency suggestions from Codex.

alexander-yevsyukov · 2026-06-17T23:41:11Z

+  and repository-level invariants.
+- `README.md`: user-facing overview, installation, configuration, modes, flags,
+  and normal operation.
+- `EMBEDDING.md`: embedding syntax, source markers, patterns, fences,


We probably need to have a docs/ directory to which we'd put user-facing documentation.

Expect the EMBEDDING.md file to be split in task-focused documents. It is helpful to have shorter documents referenced from a TOC, rather than a big one file.

Also, please assume that this documentation will be used by agents acting on the documentation from other repositories in SpineEventEngine and TeamDev organizations.

Make it easy to digest for both humans and agents.

The showcase folder contains documentation, guides, and end-to-end tests in one place in the following PR: #52.

alexander-yevsyukov · 2026-06-17T23:41:49Z

+When behavior changes, trace the complete path instead of patching only the
+first function that exposes the symptom.
+
+## Package Map


This is project info, not general agents orientation.

I've moved it to the PROJECT.md file.

alexander-yevsyukov · 2026-06-17T23:42:16Z

+  a Go keyword.
+- `test/resources/`: parser, embedding, configuration, and source-code fixtures.
+
+## Parser And Embedding Rules


Event deeper project info. Does not belong to general agent orientation content.

alexander-yevsyukov · 2026-06-17T23:43:34Z

+  code, tests, fixtures, and project flows.
+---
+
+# Write documentation (repo-specific)


What does repo-specific mean in the context of this repo. You don't share skills via config and agents repo. Do you?

I've removed the repo-specific mention.

Vladyslav-Kuksiuk · 2026-06-18T15:01:02Z

@copilot review

Copilot

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

Vladyslav-Kuksiuk · 2026-06-18T15:22:46Z

 #### 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:


It is a latest Go version.

Vladyslav-Kuksiuk · 2026-06-18T15:26:57Z

 ## 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


It is a latest Go version.

Copilot · 2026-06-18T15:17:48Z

@copilot review

Reviewed. I re-checked the branch and CI context: the branch currently uses Go 1.26.4, go test ./... passes locally, and recent Run Tests workflow runs on agents are successful. No additional code changes are required from the Copilot findings at this point.

alexander-yevsyukov

LGTM

Vladyslav-Kuksiuk added 2 commits June 5, 2026 17:11

Add AGENTS.md and skills.

2dab969

Improve agents skills segregation.

3e47bc6

Vladyslav-Kuksiuk requested review from MykytaPimonovTD and Oleg-Melnik June 8, 2026 09:14

Vladyslav-Kuksiuk self-assigned this Jun 8, 2026

Merge remote-tracking branch 'refs/remotes/origin/master' into agents

b30ee47

MykytaPimonovTD approved these changes Jun 12, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread .agents/skills/go-engineer/SKILL.md

Comment thread skills/go-tester/SKILL.md Outdated

Remove redundant point.

9022cbe

alexander-yevsyukov reviewed Jun 17, 2026

View reviewed changes

alexander-yevsyukov requested a review from Copilot June 17, 2026 00:04

Copilot started reviewing on behalf of alexander-yevsyukov June 17, 2026 00:05 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

alexander-yevsyukov requested changes Jun 17, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread .agents/skills/go-engineer/SKILL.md

Vladyslav-Kuksiuk added 3 commits June 17, 2026 09:38

Update Go version.

9080e56

Improve type package identification in AGENTS.md.

48e3e5f

Add main application to .gitignore.

169ac89

Vladyslav-Kuksiuk requested a review from alexander-yevsyukov June 17, 2026 11:15

Oleg-Melnik requested changes Jun 17, 2026

View reviewed changes

Move skills under .agents folder.

118a0dc

Vladyslav-Kuksiuk requested a review from Oleg-Melnik June 17, 2026 15:24

Oleg-Melnik requested a review from Copilot June 17, 2026 15:29

Copilot started reviewing on behalf of Oleg-Melnik June 17, 2026 15:30 View session

Copilot AI reviewed Jun 17, 2026

View reviewed changes

Comment thread .github/workflows/check.yml Outdated

Comment thread .github/workflows/build_binaries.yml Outdated

Comment thread go.mod

Oleg-Melnik approved these changes Jun 17, 2026

View reviewed changes

alexander-yevsyukov requested changes Jun 17, 2026

View reviewed changes

alexander-yevsyukov reviewed Jun 17, 2026

View reviewed changes

Comment thread AGENTS.md

alexander-yevsyukov reviewed Jun 17, 2026

View reviewed changes

Vladyslav-Kuksiuk added 10 commits June 18, 2026 10:50

Update GO version in workflows.

d4111a8

Remove Skills section from AGENTS.md.

b5821fc

Extract PROJECT.md.

bbac43b

Merge remote-tracking branch 'refs/remotes/origin/master' into agents

344d1ac

Extract Processing Flow to engineering skills.

657a0ab

Improve cost-efficiency for AI agents.

7a62893

Improve readability.

57d0408

Update Go version in audit.

020a219

Improve readability.

ed073c4

Provide skills readme.

ce601fa

Vladyslav-Kuksiuk requested a review from Copilot June 18, 2026 14:59

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Copilot started reviewing on behalf of Vladyslav-Kuksiuk June 18, 2026 15:10 View session

Copilot started work on behalf of Vladyslav-Kuksiuk June 18, 2026 15:15 View session

Copilot finished work on behalf of Vladyslav-Kuksiuk June 18, 2026 15:18

Improve Go version mentioning.

8e58399

Vladyslav-Kuksiuk requested a review from alexander-yevsyukov June 18, 2026 15:28

alexander-yevsyukov approved these changes Jun 18, 2026

View reviewed changes

Vladyslav-Kuksiuk merged commit 81156c8 into master Jun 18, 2026
3 checks passed

Vladyslav-Kuksiuk deleted the agents branch June 18, 2026 15:41


		## Project Overview

		`embed-code-go` is a Go 1.22.1 command-line application. It scans Markdown and


		Apply multiple skills when a task crosses these boundaries.

		## Project Overview

Conversation

Vladyslav-Kuksiuk commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexander-yevsyukov commented Jun 17, 2026

Uh oh!

alexander-yevsyukov commented Jun 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

alexander-yevsyukov left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Oleg-Melnik commented Jun 17, 2026

Uh oh!

Oleg-Melnik left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Oleg-Melnik left a comment

Choose a reason for hiding this comment

Uh oh!

alexander-yevsyukov left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Vladyslav-Kuksiuk commented Jun 8, 2026 •

edited

Loading