This guide is for contributors and maintainers working on this repository. To install assistant templates in your own project without cloning this repo, follow toolkit installation instead.
When working from a fork, origin points to your fork and upstream points to
the source repo. Verify your remotes first. Use this workflow without losing the
ability to sync cleanly from upstream.
git remote -v
# origin https://github.com/<you>/aicodeguide.git (fetch/push)
# upstream https://github.com/automata/aicodeguide.git (fetch/push)Keep main as a clean mirror of upstream/main. Never commit directly on
main — always work on a feature branch.
Use Node.js 22 or newer and run the checks before committing:
git checkout main
git checkout -b feature/<short-name>
# ... edit files ...
npm ci
npm run check
git add <files>
git commit -m "<message>"
git push -u origin feature/<short-name>Resolve failing checks before committing, and rerun them after further edits before opening or updating a PR. See Contributing and Validation for check coverage and manual client acceptance steps.
Open a pull request from your feature branch on your fork, targeting
automata/aicodeguide:main. Keep the branch until the upstream PR is merged.
Do not merge fork-only commits into your mirror branch.
For changes that will remain specific to your fork, keep a separate integration
branch (for example, fork-main). Merge feature branches there and merge
upstream/main into that branch as needed; it is not a mirror and can diverge.
Run this periodically to pull in changes from the original repo:
git checkout main
git fetch upstream
git merge --ff-only upstream/main
git push origin mainIf --ff-only fails, stop: local main contains divergent history. Preserve
those commits on a separate branch and reconcile deliberately. Do not reset or
force-push a branch containing work you have not preserved.
Then rebase any in-progress feature branch on top of the refreshed main:
git checkout feature/<short-name>
git rebase mainRebasing rewrites commits. Coordinate with collaborators before rebasing a
shared branch; updating its remote may require an explicitly approved
git push --force-with-lease.
After confirming that the PR is merged and its changes are present in the
synced main:
git checkout main
git branch -d feature/<short-name>
git push origin --delete feature/<short-name>After a squash or rebase merge, git branch -d may refuse because commit IDs
differ. Verify the merged changes before deciding whether to force-delete the
local branch; refusal is not a reason to discard unverified work.
Third-party instructions, skills, and agents must originate from the actual upstream project, not be recreated from memory. Fetch a pinned commit:
curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/<commit-sha>/<path> -o <path>Record exact provenance (commit URL, license, fetch date, checksums) in a SOURCES.md
next to the vendored files - see toolkits/copilot/SOURCES.md
for the pattern. Preserve upstream copyright and license notices when distributing
or installing copies. Local safety and compatibility fixes are allowed only when
documented as adaptations with their purpose and checks; do not label adapted
files "verbatim". Keep unrelated upstream formatting unchanged.
Repo-owned scaffolds, installation tools, tests, and CI may be authored here.
Follow Contributing and Validation for building a toolkit
archive and the approvals required for distribution or publication. Generated
.tgz archives are build artifacts, not source files to commit. Keep consumer
setup instructions in the installation guide rather
than duplicating version-specific commands here.