📘 template

https://kyaulabs.com/

About

This repository is the basis for all other repositories created here at KYAU Labs.

• GitHub limits repositories to 10GB of cache space for actions.
• GitHub limits users/organizations to 0.5GB of artifact storage.

Keep these factors in mind when setting up repositories.

• About
• Dependencies
• New Repository
  • Clone this Template
  • Initialize Repository
  • Add License
  • Add .gitignore
  • Update README.md
  • Configuration Files
• Git Hooks
  • Configuration
  • Install Script
• Initial Commit
  • Stage All
  • Commit
  • Push
• Repository Settings
  • General
  • Collaborators and Teams
  • Branches
  • Webhooks
• Issue Labels
• Coding Harness
  • Quick-start loop
  • Primary agents
  • Built-in subagents
  • Custom agents
  • Slash commands
  • Skills (on-demand)
  • Project context — living docs
  • Activation
• Conventional Commits
  • Type
  • Scope
  • Subject
  • Body
  • Footer
  • Examples
• Changelog
• Attribution

Dependencies

Install project dependencies via Composer and npm.

composer install
npm install

Test setup

No bootstrap step needed — tests/Pest.php ships pre-configured with the arch tests from .opencode/docs/conventions.md (no debug functions, strict types). The four test subdirectories (Unit, Feature, Integration, Browser) are also pre-created.

Run the test suite after composer install:

php vendor/bin/pest --coverage

Tool	Via	Purpose
php-cs-fixer	Composer	PHP code style (PSR-12)
pestphp/pest	Composer	Testing framework (TDD)
pestphp/pest-plugin-arch	Composer	Architecture tests
pestphp/pest-plugin-browser	Composer	Browser tests (Playwright)
sass	npm	SCSS → CSS compilation
uglify-js	npm	JavaScript minification
eslint	npm	JavaScript linting
stylelint	npm	SCSS linting
commitlint	npm	Commit message validation
@commitlint/config-conventional	npm	Conventional commits preset for commitlint
git-cliff	npm	Changelog generation
playwright	npm	Browser testing

Gitleaks

Gitleaks scans commits for secrets at pre-commit time. Install globally via your package manager or from gitleaks/releases.

Harness tools

In addition to the Composer and npm dependencies above, the coding harness uses the following external tools. Install them on the dev machine to enable the corresponding agents:

Tool	Purpose	Install
OpenCode	The coding harness platform	See opencode.ai/docs
Semgrep	SAST scanning (@semgrep agent)	pip install semgrep or releases
OpenCodeReview (ocr)	Code review (@code-review agent)	docs
gitleaks	Secrets scanning at pre-commit	releases

New Repository

Base the repository off of the organization template repository.

Clone

git clone https://github.com/kyaulabs/template <REPOSITORY_NAME>
cd <REPOSITORY_NAME>
rm -rf .git

Init

Initialize your new repository.

git init

Add Aurora Submodule

The Aurora PHP Framework is a required submodule. Add it to the repository:

git submodule add https://github.com/kyaulabs/aurora aurora

Add LICENSE

Add in a LICENSE of choice, using the filename LICENSE.txt, LICENSE.md or LICENSE.rst. There are two main repositories of licenses to choose from:

• GNU: GNU APGLv3 / GNU GPLv3 / GNU LGPLv3
• General: Apache License 2.0 / MIT License / Mozilla Public License 2.0
• CC: CC BY 4.0 / CC BY-SA 4.0 / CC BY-ND 4.0 / CC BY-NC 4.0 / CC BY-NC-SA 4.0 / CC BY-NC-ND 4.0

Add .gitignore

Add a .gitignore template from @github/gitignore (modification required).

Update README.md

Take this time to update the README.md with at least basic repository information and a hopeful table of contents. It is okay if most sections are blank.

Configuration Files

Several files reference kyaulabs/template and must be updated to reflect your new repository:

File	What to update
cliff.toml	All github.com/kyaulabs/template URLs → new repo location
composer.json	name and description fields
package.json	name and description fields
opencode.json	build agent prompt references the project; update repo-specific pointers
CONTEXT.md	Fill in the domain glossary, entities, invariants, and non-goals (or run /prime to draft)
commitlint.config.js	Remove any unused types from type-enum if needed

Add Actions

Make sure you add the appropriate actions from the @kyaulabs/template-workflows repository.

Edit the workflow accordingly as all workflows come with only manual activation set with automatic activation commented out.

on:
  workflow_dispatch: {}
#on:
#  push:
#    branches: [ "main", "develop" ]
#  workflow_dispatch:

Git Hooks

Configuration

The repository ships with a commitlint.config.js using the project's custom type-enum (see Conventional Commits below). No generation step is required — edit the file directly only if you need to add or remove commit types.

Install Script

Run the install script to symlink hooks from .github/hooks/ into .git/hooks/.

bash .github/scripts/install-hooks.sh

The script backs up any existing hooks and symlinks in the pre-commit (lint + gitleaks) and commit-msg (commitlint) hooks.

Initial Commit

Stage All

Add all files to the repository. The first command utilizing the dry-run switch to make sure you do not need any last minute additions to .gitignore.

git add -A -n
git add -A

Commit

Push the initial commit with (non-commitlint verified message).

git commit -S -a -m "ignore: here be dragons"

The ignore type is project-specific (defined in commitlint.config.js) and excluded from the changelog. It exists for the initial repository commit and is otherwise unused — do not adopt it for normal commits.

Finally set the main branch name.

git branch -M main

Push

Add the remote origin and push the branch to origin.

git remote add origin git@github.com:kyaulabs/<REPOSITORY_NAME>.git
git push -u origin main

Repository Settings

In order to have proper repository security, some settings need to change. Open up the repository settings by clicking on the Settings tab at the top of the repository.

General

Upload an image to customize the repository's social media preview.

• Image should be 1280×640px

Under the Features section enable Sponsorships and then disable anything that is not being using.

Collaborators and Teams

Under manage access click on Add people. In the search box enter and select @kyaulabs-bot then change the role to Write.

@kyaulabs-bot

Branches

Create a new branch protection rule by clicking Add branch protection rule.

• Branch name pattern: main
• Protect matching branches:
  • Require a pull request before merging
  • Require approvals (1)
  • Require status checks to pass before merging — add check (the CI workflow job)
  • Require signed commits

Click Create.

Create another branch protection rule with the following:

• Branch name pattern: **/**
• Protect matching branches:
  • Require signed commits

Webhooks

If you would like this repository to output to a channel on Discord you will need to create a webhook on both ends.

In Discord goto the Server Settings > Apps > Integrations and click New Webhook. Give it an avatar, name and select a channel for it to output to.

Back on GitHub on the Settings > Webhooks page, create a new hook by clicking Add webhook.

• Payload URL: Click on Copy Webhook URL in Discord to get this URL.
• Content type: application/json
• Let me select individual events:
  • Commit comments Forks Issues Page builds Pull requests Pushes Releases Statuses Wiki

Click on Add webhook.

Issue Labels

Organization level issue labels work in conjunction with conventional commits. We use a modified version of the TIPS system called TPS or Type, Priority and Status as a way to label issues such that they can be organized and assigned accordingly.

In order to properly label something be sure to include at least one type, a single priority and it's current status. Optional labels may be added at your discretion.

T - Type: Directly corresponds to the conventional commits type.

Group	Label	Color	Description
Type	feature	#41d6c3	🚀 Feature
Type	patch	#41d6c3	🩹 Patches
Type	bug	#ff5050	🐛 Bug
Type	documentation	#c0e6ff	📝 Documentation
Type	performance	#41d6c3	⚡️ Performance
Type	refactor	#ffa572	♻️ Refactor
Type	style	#ffa572	💄 Styling
Type	test	#ffd791	⚗️ Testing
Type	ci/cd	#ffd791	👷 CI/CD
Type	chore	#ffd791	🔮 Misc
Type	security	#ff5050	🔒️ Security

P - Priority: The urgency of the issue/task.

Group	Label	Color	Description
Priority	critical	#800000	Security-related/Project-breaking
Priority	high	#c11c00	Foundational / Important
Priority	medium	#f39a4d	Basic / Normal
Priority	low	#8cd211	Additional / Polish

S - Status: Current progress.

Group	Label	Color	Description
Status	done	#0e8a16	Complete
Status	in progress	#fbca04	Currently Working On
Status	testing	#fbca04	Testing Ideas / Methods
Status	under construction	#fbca04	Beginning Stages

Optional: Two other groups are included for convinience.

Group	Label	Color	Description
Feedback	brainstorming	#db2780	Coming Up w/ New <Type>
Feedback	help wanted	#db2780	Help Requested on <Type>
Feedback	research	#db2780	<Type> Needs Research
Feedback	request for comments	#db2780	External Opinions Needed on <Type>
Other	good first issue	#4e3cb2	Good Issue for First Time Contributor
Other	duplicate	#cfd3d7	Duplicate <Type>
Other	invalid	#cfd3d7	Invalid <Type>
Other	on hold	#cfd3d7	Currently On Hold
Other	won't fix	#cfd3d7	This Will Not Be Fixed

Coding Harness

This template ships with an OpenCode coding harness — a collection of agents, skills, and commands that enforce project conventions during AI-assisted development. The harness lives under .opencode/ and is wired into OpenCode via opencode.json.

Reference docs:

• AGENTS.md — AI-facing instructions: stack, boundaries, conventions, and available tools (loaded by every session)
• CODING_HARNESS.md — Orientation guide: built-in features, pipeline overview, and pointers (agents load AGENTS.md as the authoritative source)
• CONTEXT.md — Domain glossary, entities, invariants, boundaries, non-goals (living doc — agents read and update it)
• adr/ — Architecture Decision Records in Nygard format (living docs — supersede, don't edit)
• opencode.json — Wires instructions + agent definitions + permissions into the coding agent

Quick-start loop

The full engineering pipeline, end to end:

brainstorming → prototype (if needed) → writing-plans → @tdd (per task) → verification-before-completion → /check → @code-review

1. Brainstorm — load the brainstorming skill; refine the idea through one-question-at-a-time grilling, propose 2–3 approaches, present the design in sections, get user approval. Saves a spec to docs/specs/.
2. Prototype (if needed) — load the prototype skill; build throwaway code to answer technical viability questions before committing to a plan. Delete after capturing the answer.
3. Plan — load the writing-plans skill; break the approved spec into bite-sized TDD tasks with exact file paths, interfaces, complete code, and verification commands. Saves a plan to docs/plans/.
4. Implement — invoke @tdd per task (Red → Green → Refactor, vertical slices). The harness enforces 80% line coverage.
5. Verify — load the verification-before-completion skill; re-run tests, confirm green, confirm no debug artifacts remain, confirm lint passes.
6. Gate — run /check (php-cs-fixer + stylelint + eslint + pest --coverage). On green, commit with a conventional message.
7. Review — invoke @code-review before push.

For non-trivial or cross-cutting changes, insert @architect before step 4. For bugs, use @debug (disciplined 6-phase loop) before @tdd on the fix. For architectural entropy, run /improve-architecture on a cadence.

Primary agents

Agent	Purpose
Build	Default mode — full tool access; enforces mandatory @tdd and the project's hard boundaries
Plan	Restricted mode — analysis and planning only; cannot edit files or invoke code-modifying subagents

Press Tab to switch between Build and Plan during a session.

Built-in subagents

Agent	Purpose
@explore	Read-only codebase exploration — file patterns, keyword search
@scout	External docs + dependency research (clones upstream repos)
@general	Multi-step research, full tool access

Custom agents

Agent	When to use
@tdd	Any new feature or bug fix requiring tests (mandatory for new code)
@test-audit	Auditing an existing test suite for quality
@code-review	Reviewing staged changes before push (uses ocr)
@architect	Read-only evaluation of a proposed change against CONTEXT.md + ADRs before implementation
@resolve-merge-conflicts	Resolving in-progress git merge/rebase conflicts
@semgrep	SAST scanning — diff audit + full scan (PHP/JS/secrets)
@debug	Investigating bugs — disciplined 6-phase loop: feedback loop → reproduce → hypothesise → instrument → fix → post-mortem
@docs-writer	Generating PHPDoc, RCS headers, and documentation

Slash commands

Command	Purpose
/prime	Draft or regenerate CONTEXT.md from the codebase
/check	Pre-push gate: php-cs-fixer + stylelint + eslint + pest --coverage (80%)
/release	git-cliff changelog + signed tag + gh release command
/deploy	Post-pull production deploy — asset rebuild, opcache clear, log tail
/research	Cited research via @scout + web (see .opencode/docs/research.md)
/build-assets	Rebuild minified CSS and JS from SCSS/JS sources
/security	SAST scan + dependency CVE audit in one pass
/improve-architecture	Scan codebase for deepening opportunities → Obsidian markdown report
/handoff	Compact current conversation into a handoff document for another session

Skills (on-demand)

Skills load when an agent needs them — they are not loaded into every session. Load one explicitly with the skill tool, or let the agent pull it when the task matches.

Category	Skills
Engineering pipeline	brainstorming, prototype, writing-plans, verification-before-completion
Visual language	frontend-design, scss-mobile-first, accessibility
Frontend structure	frontend-architecture, aurora-page
Defensive coding	security-coding
Data	database
Domain & architecture	domain-context, adr, systems-design
Standards & process	conventional-commits, rcs-header, pest-browser, audit-deps, writing-skills

Project context — living docs

• CONTEXT.md — the domain's what and why: glossary, entities, invariants, boundaries, non-goals. Agents read it before domain-coupled work and update it when domain language changes. Draft a fresh one with /prime.
• adr/ — Architecture Decision Records. Write an ADR (copy adr/0000-template.md) for hard-to-reverse or cross-cutting decisions. Supersede, never edit. Run @architect before non-trivial changes to check for ADR conflicts.

Activation

The harness is active in any OpenCode session opened in this repo — no manual steps beyond installing OpenCode and running composer install / npm install. Git hooks (lint + gitleaks + commitlint) are activated separately via bash .github/scripts/install-hooks.sh.

Conventional Commits

In order to abide by the conventional commit guidelines and in return get auto-generated changelogs, use the following.

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Type

[required] (!empty) value = {
  'build',
  'chore',
  'ci',
  'docs',
  'feat',   # this correlates with MINOR in Semantic Versioning
  'fix',    # this correlates with PATCH in Semantic Versioning
  'patch',  # this correlates with PATCH in Semantic Versioning
  'perf',
  'refactor',
  'revert',
  'style',
  'test',
  'ignore'  # this correlates with CHANGELOG ignores
}

A trailing ! indicates a BREAKING CHANGE (correlating with MAJOR in Semantic Versioning).

Scope

[optional] {lowercase | camelCase}

A noun describing a section of the codebase surrounded by parenthesis.

Subject

[required] (!empty) {lowercase | camelCase} (max-length: 100)

A short summary of the code changes, without a trailing full-stop.

Adding [skip ci] will skip all push and pull_request workflows.

Body

[optional] {freeform} (max-length: 100)

Longer commit body with additional contextual information about the code changes.

Footer

<token>: <value>
[optional] (max-length: 100)
token (Sentance-case) = {
  'BREAKING CHANGE',    # Exception to the rule
  'Acked-by',
  'Cc',
  'Fixes',
  'Helped-by',
  'Refs',
  'Reviewed-by',
  'Signed-off-by',
}

Any number of tokens may be included.

Examples

The following are all examples of valid commit messages.

The commit message will also go through validation with commitlint upon issuing git commit.

feat(player): begin new implementation of input controller

As per #123 recommendation input contoller is now based on blah.

Basic movement added.

Acked-by: Alice <alice@example.com>
Signed-off-by: Bob <bob@example.com>
Refs: #123
Refs: 676104e, a215868

fix: array parsing issue

Fixes: #42
Cc: Z
Reviewed-by: Z
Signed-off-by: Z

chore(release): v0.0.1 [skip ci]

Changelog

Once you have published at least one proper commit using conventional commits syntax you will be able to generate a changelog. The recommended path is the /release command (see Slash commands in the Coding Harness section), which drives git-cliff end-to-end. The manual flow below is a fallback.

Manual changelog

git cliff --tag 0.0.1

After the initial run of git-cliff all subsequent runs should detect the version automatically.

git cliff

A typical manual workflow should look like the following.

git add -A                      # add all un-indexed and changed files to the commit
git commit -S -a -m "<message>" # add a conventional commit message and sign the commit
git cliff                       # generate a new changelog
git add CHANGELOG.md            # add the changelog file to the commit
git commit --amend --no-edit    # ammend the added file to the previous un-pushed commit
git push -u origin develop      # finally, push the commit

Attribution

• OpenCode — the coding harness platform this template targets
• Aurora — the PHP framework included as a submodule
• Pest — the PHP testing framework (TDD)
• php-cs-fixer — PHP code style (PSR-12)
• Commitlint — commit message validation
• git-cliff — changelog generation
• Semgrep — static analysis security testing
• gitleaks — secrets scanning at pre-commit
• OpenCodeReview (ocr) — code review tooling used by the @code-review agent