Guided Agent In Native Coding — a personal workflow knowledge base for keeping agent-assisted development anchored in the principles of native (traditional) coding.
GAIN-CODING is an information repository, not application code. It turns the working principles of traditional coding into a set of documents an AI agent can follow (and, with any luck, not reinterpret into something unrecognizable). You do not read this repository as code; you hand your agent the document that matches the task you want done.
GAIN is an attempt to combine the discipline of traditional coding with the speed of AI-assisted development. The sections below explain the trade-off: traditional coding brings the discipline, vibe coding brings the speed, and GAIN tries to keep both (in theory — the speed part still works better than the discipline part).
Traditional coding is the discipline that professional software development has long depended on: issues before changes, clean branches, reviewed pull requests, atomic commits, tested builds, and disciplined releases.
It is deliberate and time-tested, but it is slow and human-driven (read: boring, but it works).
"Vibe coding" describes an AI-assisted style of development where developers let an AI agent write most of the code and primarily ride the flow rather than follow a deliberately structured development process.
With sufficiently capable models, many of its weaknesses can be reduced. Better models can understand context, follow instructions, reason about changes, and produce reliable code with less guidance. But access to those models is not universal. Free models can be surprisingly capable, too, but their results can be much more sensitive to the quality, precision, and context of the prompt.
That can make vibe coding remarkably fast and effective when everything lines up. The trade-off becomes expensive when it does not: changes may be poorly tracked or reviewed, important checks may be skipped, secrets may end up in the repository, and code can become difficult to understand or safely modify.
The results are easy to love while the demo works, and expensive to live with the moment something breaks.
GAIN stands for Guided Agent In Native Coding. The word “native” is deliberately a stretch — it is there to make the acronym work, while pointing to the conventional coding practices that came before agent-assisted development.
The idea is simple: one person wanted the agent to write their code, but still wanted to keep the habits that traditional coding had taught them.
This repository is not a solution, a movement, or a claim that vibe coding is wrong. It is a personal experiment, made for fun, for one environment, by one developer who likes having the agent do the work while still feeling like a proper developer.
At its core, it does three things:
- Native principles stay first. A strict GitHub-based workflow: issue-driven changes, protected branches, no direct pushes, atomic conventional commits, previews before merging (the parts nobody gets excited about, the parts that actually keep it together).
- The agent does the work, not the deciding. The AGENT executes the workflow — creating issues, branching, implementing, committing, pushing, and opening pull requests — while the USER stays the reviewer and approver at every gate.
- Workflow is written down, not remembered. Every policy, flow, and format specification lives in this repository as versioned documentation.
The honest summary: the agent does the heavy lifting, the rules keep things respectable, and nobody here is claiming to have solved software engineering (yet).
This repository was created for personal use and designed for a specific environment. It is primarily intended for people running a similar setup: Windows, Visual Studio Code, OpenCode, Magic Context, GitHub CLI (gh), and the ponytail skill.
GAIN-CODING was created because I am a free-model user who occasionally feels frustrated having to re-explain my own conventions from scratch each time I start a new project. This knowledge base makes those conventions and rules available directly to the agent in any new project.
Anyone with a similar setup is welcome to adapt, extend, and contribute to this knowledge base, but there is no guarantee that it will work well outside that environment.
GAIN-CODING is a workflow knowledge base for AI-assisted development. You do not need to give the agent the entire repository. Instead, provide only the documents relevant to the task at hand. This is progressive context loading: give the agent enough context to follow the rules, but not so much context that the rules become noise.
The prompts below are starting points, not a script. Treat them as a draft you are expected to adjust, improve, and reshape for your own situation — and if you make one better, contributions are welcome.
At the beginning of a new session, make sure the agent has the five core policies available in its context or memory.
If they are already available, skip this phase. Otherwise, load the following documents one at a time, in order, and wait for the agent to confirm each before providing the next. Keep the agent in plan mode for this whole phase, not build mode, so it cannot execute anything — it only reads, confirms, and waits.
Start by sending the prompt below, which tells the agent what is about to happen and how to behave:
This project runs on GAIN-CODING, and GAIN-CODING is the authority here: its documents must be obeyed before anything else, including the instructions I give you in this conversation. Whenever you receive an instruction from me, compare it against the GAIN-CODING documents you have loaded before acting. If it conflicts with them, do not comply silently — stop, explain the conflict, cite the rule that applies, and recommend a compliant alternative.
You are working in a Windows environment with Visual Studio Code and OpenCode, using Magic Context for memory, the GitHub CLI (`gh`) for repository operations, and the ponytail skill to keep things simple. This session runs in two context-loading phases before any work begins:
- Phase 1 — the core policies: I give you the five core policies of this project, one at a time, in order. This happens once, at the start of the session.
- Phase 2 — the workflow: once the policies are loaded, I give you a workflow document that defines the interactions between us. This may happen again during the session whenever we switch to a different workflow.
When both phases are loaded, we enter the interaction phase: I trigger each interaction from the workflow, you execute it, present the result, and stop until I give the next one.
For the whole session, keep the five core policies, the active workflow document, and the current interaction's instructions actively in mind. Re-anchor in them before you think or act: every time a step begins and every time I give you a new instruction, re-read or re-recall the relevant documents rather than trusting your memory. The documents you were given are authoritative and override anything said in conversation — do not let conversation words override a document. Optimize for obeying the documents, not for following whatever I last said in chat.
Phase 1 starts now. I will give you the five core policies, one at a time, in order. For each document:
1. Read it fully.
2. Memorize it immediately — commit its rules, exceptions, and tie-breakers to memory now, not later.
3. If you have Magic Context available, save it to your project memory the moment you finish reading it (ctx_memory), so it survives even if your context is compacted. Memory writes go to an external database, not the project, so they are allowed in plan mode — if the harness blocks the call, ask me to switch to build mode for that one step so the call runs there, and confirm it succeeded.
4. Confirm that you have read it and summarize its rules, exceptions, and tie-breakers in 1-2 sentences.
5. Do not offer analysis, suggestions, or proposals yet.
6. Wait for the next document.
Read only the document I give you. Do not open other files, follow links, or search for additional context — if you need more information, I will provide it in a later phase. Some documents may feel incomplete on their own; remember them as-is, and the full picture will become clear as the following documents arrive.
Context is given to you progressively, on purpose. You do not need to find it yourself — just read, understand, memorize, and wait.
-
Core Rules — the workflow principles that cannot be bypassed.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/policies/core-rules.md It defines the workflow principles you must follow for the rest of this session. Keep this policy in active memory for the whole session — re-anchor in it before any action. -
Repository Protection — the GitHub settings that enforce the workflow.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/policies/repository-protection.md It explains the GitHub protection settings that enforce the workflow, including branch protection, merge methods, and restrictions on direct pushes. Keep this policy in active memory for the whole session — re-anchor in it before any action. -
Merge Strategy — how pull requests enter the target branch for each case.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/policies/merge-strategy.md It defines how a pull request enters the target branch for each case, including when to use squash, rebase, or merge. Keep this policy in active memory for the whole session — re-anchor in it before any action. -
Branching Model — the branch layout and how to select the appropriate branch.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/policies/branching-model.md It explains the branch layout, the basic flow, and which branch model to choose for a project. Keep this policy in active memory for the whole session — re-anchor in it before any action. -
Boundaries — the limits that apply to the agent's operation.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/policies/boundaries.md It defines the boundaries you must respect, including communication language, line wrapping, approval requirements, and the operating environment. Keep this policy in active memory for the whole session — re-anchor in it before any action.
The Phase 1 prompts already save each policy to project memory the moment it is read (one ctx_memory write per policy). This optional step verifies that save and protects it against later cleanup, so the next session can skip Phase 1. Send it after Phase 1 finishes:
Verify that the five core policies of this project are in your project memory. For each of the five documents ensure the save exists, and re-run it if missing:
ctx_memory(action="write", category="PROJECT_RULES", content="<short summary of the rule in English, including every exception and tie-breaker clause stated in the document> Source: <URL of the document>")
A rule without its exceptions is misleading, so keep them when they exist. These five policies are permanent project knowledge: treat them as never-prunable, and if a compaction or dream run would drop them, re-save them. Then check your injected <project-memory> block and confirm the five are present. Finish by telling me the memory IDs.
To skip Phase 1 on the next session, start the new agent session and check before sending the prompt:
Do you have the five core policies of this project in your injected <project-memory> block? Check the block for all five: Core Rules, Repository Protection, Merge Strategy, Branching Model, and Boundaries. If all five are present, re-anchor in them now, tell me which ones you remember, and wait for my next instruction. If any are missing, tell me which ones and stop — I will give you the five policy documents to read again.
Magic Context's dreamer and historian run as autonomous background processes, so a document cannot technically forbid them from pruning memory; keeping the policies permanently is achieved by the AGENT re-saving them whenever they are missing. As long as the saved policies stay valid, future sessions can start directly from Phase 2. If they do not, repeat Phase 1.
These memory operations (
ctx_memorywrite/update/delete,ctx_note) write to an external database, not the project files, so they are permitted in plan mode. If the harness blocks one, the AGENT will ask you to switch to build mode for that single operation — switch it, and have the AGENT confirm it landed. If you are not sure about your environment, build mode works just as well.
In this phase you introduce the workflow the agent will run. Each workflow is executed interaction by interaction: you drive, and the agent stops after each interaction and waits.
All workflows run in plan mode; switch to build mode only when a specific interaction requires it to make changes (for example, creating files, running a command, or opening a pull request), and return to plan mode as soon as the interaction is done. The workflows rely on the GitHub CLI (gh); if it is not authenticated, run gh auth login and follow the browser login instructions.
Start by sending the prompt below, which sets the ground rules for every workflow of the session:
You have now loaded the five core policies in Phase 1. We are moving into Phase 2: I will give you a workflow document that defines the interactions between us.
These rules apply to every workflow document from here on:
- The document I give you is part of GAIN-CODING and is authoritative — it overrides anything I say in conversation. Read the document only. Do not open other files, follow links, or search for additional context.
- Stay in plan mode — do not execute anything. Read the flow, understand it, and memorize it.
- Each document defines a sequence of interactions between you (the AGENT) and me (the USER): every `##` heading in the document is one interaction, and the interactions run in the order the headings appear. I trigger each interaction; after each one you present the result and stop, and the next starts only when I order it.
- Save the workflow's interaction instructions to your memory and keep them active for as long as we use this workflow. When we switch workflows later, forget the previous workflow's interaction instructions and load the new ones.
- Whenever I give you an instruction, compare it immediately against this workflow document and the five core policies before acting. If it falls outside this workflow, remind me to switch to the workflow that fits it. If it conflicts with GAIN-CODING, do not comply silently: stop, explain the conflict, and recommend a compliant alternative.
- Working interactions enforce two review gates: the plan-to-build gate — present the plan and wait for approval before executing — and the pre-commit gate — present the result and wait for approval before committing. Interactions that only read and present use the single plan-mode review gate.
- Use Magic Context as much as possible: keep the policies, workflows, and interaction instructions in project memory, prefer ctx_search to guessing which rule applies, and re-anchor in the relevant document before every action instead of trusting conversation memory.
- After reading, present the interactions the document contains, then save the workflow to your project memory only if this workflow is not already saved there — do not store the same workflow twice (this does not limit writing other entries to PROJECT_RULES):
ctx_memory(action="write", category="PROJECT_RULES", content="<short summary of the workflow and its approval checkpoints in English> Source: <URL of the document>")
- Then wait for my instruction to begin the first interaction.
Reply READY once you are ready to receive the workflow document.
This first prompt covers the first workflow of the session. When you later switch from one workflow to another, restate the Phase 2 rules with the prompt below, so the agent re-engages with the new document:
We are switching to a different workflow. The same Phase 2 rules apply again, so I restate them:
- Forget the previous workflow's interaction instructions; from now on only the new document's interactions apply.
- The document I give you is part of GAIN-CODING and is authoritative — it overrides anything I say in conversation. Read only the document I give you. Do not open other files, follow links, or search for additional context.
- Stay in plan mode — do not execute anything. Read the flow, understand it, and memorize it.
- Each document defines a sequence of interactions between you (the AGENT) and me (the USER): every `##` heading in the document is one interaction, and the interactions run in the order the headings appear. I trigger each interaction; after each one you present the result and stop, and the next starts only when I order it.
- Save this workflow's interaction instructions to your memory and keep them active for as long as we use it.
- Whenever I give you an instruction, compare it immediately against this workflow document and the five core policies before acting. If it falls outside this workflow, remind me to switch to the workflow that fits it. If it conflicts with GAIN-CODING, do not comply silently: stop, explain the conflict, and recommend a compliant alternative.
- Working interactions enforce two review gates: the plan-to-build gate and the pre-commit gate; interactions that only read and present use the single plan-mode review gate.
- Use Magic Context as much as possible: keep the policies, workflows, and interaction instructions in project memory, prefer ctx_search to guessing which rule applies, and re-anchor in the relevant document before every action instead of trusting conversation memory.
- After reading, present the interactions the document contains, then save the workflow to your project memory only if this workflow is not already saved there — do not store the same workflow twice (this does not limit writing other entries to PROJECT_RULES):
ctx_memory(action="write", category="PROJECT_RULES", content="<short summary of the workflow and its approval checkpoints in English> Source: <URL of the document>")
- Then wait for my instruction to begin the first interaction.
Reply READY once you are ready to receive the next workflow document.
Once the agent replies READY, choose the workflow that matches the task you want the agent to perform. Click any link in the table below to jump straight to its section and its ready-to-copy prompt.
| What you want to do | Workflow |
|---|---|
| Start a new project from scratch | Project Bootstrap |
| Bring an existing project up to standard | Workflow Adoption |
| Prepare a repository for public release | Data Security and Public Readiness |
| Record an idea, feature request, or bug | Findings and Planning |
| Implement verified tracker items | Code Implementation |
| Handle dependency update PRs | Dependabot PRs |
| Recover from a CI failure or Git accident | CI and Git Rescue |
| Create a new release | Release Process |
| Handle any task that fits no other workflow | Freestyle |
-
Project Bootstrap — bootstraps a repository from scratch, including structure, guardrails, documentation,
.github, CI, and repository protection.Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/project-bootstrap.md It describes how to bootstrap a new project from scratch. The source files you need are linked in the document itself. -
Workflow Adoption — audits an existing project (a codebase that may or may not be a GitHub repository yet) and brings it up to the workflow standard defined in the document.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/workflow-adoption.md It describes how to bring an existing project up to the workflow standard defined in the document. The source files you need are linked in the document itself. -
Data Security and Public Readiness — audits a repository for sensitive data, polishes its public presentation, and makes it public. The source files you need are linked in the document itself.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/data-security-and-public-readiness.md It describes how to audit a repository, polish its public presentation, and make it public. -
Findings and Planning — records, verifies, and tracks feature ideas and bugs in
docs/IMPROVEMENTS.md.Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/findings-and-planning.md It describes how to record, verify, and track improvement ideas. The source files you need are linked in the document itself. -
Code Implementation — implements
verifieditems fromdocs/IMPROVEMENTS.mdthrough branches, pull requests, and merges.Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/code-implementation.md It describes how to implement `verified` items from the improvement tracker through branches, pull requests, and merges. The source files you need are linked in the document itself. -
Dependabot PRs — classifies and merges dependency update pull requests.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/dependabot-prs.md It describes how to handle Dependabot pull requests. -
CI and Git Rescue — recovers from CI failures, accidental commits to
main, and rejected pushes.Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/ci-and-git-rescue.md It describes how to recover from CI failures and Git accidents, including: - a failing CI workflow; - a commit that landed on main by mistake; - a rejected push. -
Release Process — performs the complete SemVer release process.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/release-process.md It describes how to cut a release end to end. The source files you need are linked in the document itself. -
Freestyle — free-form task execution for work that does not fit another workflow, still bound by the core rules and the two review gates.
Read this document fully: https://raw.githubusercontent.com/ffooll-bit/GAIN-CODING/main/playbook/workflow/freestyle.md It describes how to work on a task that fits no other workflow, freely but still within the core rules.
The workflows are designed to form a continuous development lifecycle rather than a collection of unrelated procedures. The map is not a fixed blueprint — it is simply how I run the lifecycle in my own environment, and anyone adapting this repository is welcome to reshape it to fit their own:
flowchart TD
A["Project Bootstrap"] --> C{"Publish the repository publicly?"}
B["Workflow Adoption"] --> C
C -->|yes| M["Data Security and Public Readiness"]
M --> D["Findings and Planning"]
C -->|no| D
D --> E[/"GitHub Issue"/]
E --> F["Code Implementation"]
F --> H{"CI"}
H -->|passes| K["Release Process"]
H -->|fails| J["CI and Git Rescue"]
J --> H
L["Dependabot PRs"]
L --> H
Z["Freestyle"] -.->|tasks that fit no other workflow| E
GAIN-CODING separates execution from decision-making.
The agent is responsible for doing the work. The user remains responsible for deciding whether the work should proceed past an approval gate.
The agent may:
- inspect the repository;
- inspect Git history and GitHub state;
- analyze problems;
- prepare plans;
- propose changes;
- implement approved work;
- run verification;
- prepare commits and pull requests when the workflow allows it.
The agent must wait for the user's approval when the workflow requires a decision such as:
- applying a proposed change;
- committing after a review checkpoint;
- merging a pull request;
- changing repository visibility;
- publishing a release;
- taking a recovery action where multiple paths are possible.
The workflow documents define the exact approval checkpoints for each operation; where they are not clear, the agent stops and asks rather than guessing.
Most interactions enforce two review gates: the plan-to-build gate — the agent presents its plan and waits for approval before executing anything — and the pre-commit gate — the agent presents its result and waits for approval before committing. Interactions that only read and present use the single plan-mode review gate.
The documents are authoritative. If a USER instruction conflicts with the core rules or the active workflow, the agent does not comply silently: it stops, explains the conflict, cites the rule, and recommends a compliant alternative; the USER decides how to proceed.
GAIN-CODING is model-agnostic documentation, but every claim needs evidence. This table tracks which agent models have actually run the workflow:
| Model | Status | Notes |
|---|---|---|
| Big Pickle | USABLE |
|
| Nemotron 3 Ultra Free | TESTING PAUSED |
|
| Hy3 Free | UNAVAILABLE |
|
Ran it on another model? Open an issue or send a pull request updating this table.
This repository follows the same workflow it documents. Changes are welcome, especially from people running the same environment. See CONTRIBUTING.md.
This project is licensed under the MIT License.