Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 22 additions & 60 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -1,87 +1,49 @@
# Copilot Instructions — repo-template
# Copilot Instructions — worldchest

## About

`repo-template` is the org baseline scaffold for new `combsmith` repositories:
click **Use this template** to create a repo pre-wired with the standard workflow
stubs and baseline files, then follow `BOOTSTRAP.md` (an agent-executable runbook)
to customize it. Its "code" is GitHub Actions workflows, Markdown docs, and a bats
suite that guards the workflows. There is no application runtime. The workflow
stubs and baseline files are a distribution artifact of the org standards in
[`combsmith/.github`](https://github.com/combsmith/.github) (`standards/`)
and are regenerated from there.
WorldChest is automatic backup, sync, restore and versioning for Minecraft Bedrock
worlds on kids' phones and tablets (parents are the buyer). This repo is pre-code:
the brief is [combsmith/incubator discussion #5](https://github.com/combsmith/incubator/discussions/5).

## Tech Stack

- **Runtime:** None — a template/scaffold repo, not a deployable application.
- **CI / config:** GitHub Actions workflow stubs (YAML) under `.github/workflows/`; Dependabot; SonarCloud.
- **Docs:** Markdown (`AGENTS.md`, `CLAUDE.md`, `BOOTSTRAP.md`, `README.md`, `SECURITY.md`).
- **Tooling:** `bats` (compliance regression tests in `tests/`), `shellcheck`, `yq`, `python3` + PyYAML, `gh` CLI.
- **Runtime:** not chosen yet. Candidates from the brief: Android app (Kotlin,
share-sheet + Shizuku), desktop companion, cloud backend for storage/versioning.
- **CI / config:** org baseline GitHub Actions stubs; `ci.yml` runs shell lint, gitleaks and a coverage job that is green until tests exist.
- **Testing / Linting:** to be set with the stack.

## Project Structure

```
.github/
workflows/ # Thin-caller stubs (keep verbatim) + ci.yml / sonarcloud.yml /
# copilot-setup-steps.yml (customize-per-stack)
copilot-instructions.md # This file
CODEOWNERS # * @combsmith/org-leads
dependabot.yml # frontend stack by default — swapped during bootstrap
standards/rulesets/
pr-quality.json # Codified copy of the org ruleset, guarded by tests/
tests/*.bats # Template-only guards: stub byte-identity, ci.yml invariants,
# gitignore baseline, ruleset drift. Removed in child repos.
AGENTS.md # Org pointer + rules specific to this template
BOOTSTRAP.md # Customization runbook for repos created from this template
sonar-project.properties # SonarCloud project key (customize per repo)
```
No application code yet. `.github/` holds the org-standard workflow stubs and this file.

## Local Dev Commands

There is no install/build/dev-run step.

- Test: `bats tests/` ← needs `bats`, `yq`, `python3` + PyYAML, GNU bash 5
(on macOS: `brew install bats-core yq` and run with Homebrew bash first on `PATH`).
- Lint: `shellcheck *.sh` (no shell scripts ship today).
- Workflow YAML validation: push a branch and let CI run, or use `act` locally.
- Install: none yet
- Test: none yet
- Lint: none yet

## Required Environment Variables

No application secrets are needed for local work. In CI, all are org-level and inherited:

- `SONAR_TOKEN`: SonarCloud analysis token; the `sonarcloud` workflow is a green no-op until present.
- `GITHUB_TOKEN`: provided automatically by GitHub Actions.
- `CLAUDE_CODE_OAUTH_TOKEN`: used by `dev-lead.yml`.
- `APP_ID` / `APP_PRIVATE_KEY`: GitHub App credentials used by `dependabot-automerge.yml`.
- `GH_PAT_WORKFLOWS`: used by `pr-review-mention.yml`.

Never commit a real token.
- None.

## Testing Framework

- `bats` regression guards in `tests/`, run by the `build-and-test` and `coverage`
jobs of `ci.yml`. They assert that each thin-caller stub is byte-identical to
its canonical template (trailing newline included — the committed stubs have
none), that `ci.yml` keeps its retry/timeout/concurrency invariants, that the
`.gitignore` secrets baseline is unmodified, and that no workflow carries a
`TODO`/`FIXME` (SonarCloud S1135).
- No coverage threshold applies — there is no application code to cover.
- None yet. First code lands with tests; the `coverage` job enforces from then on.

## Repo-Specific Overrides

- **Edit the standards, not these copies.** Workflow stubs and baseline files are
regenerated from `combsmith/.github` (`standards/`); `README.md`, `BOOTSTRAP.md`,
`AGENTS.md` and `sonar-project.properties` are generated by
`seed-repo-template.sh` in `combsmith/.github-private`. A change to any of those
made here must also land in the seeder or the next seed PR proposes reverting it.
- `ci.yml` and `sonarcloud.yml` are intentionally ahead of their canonical templates
and allowlisted in the template drift guard; keep them in step with `tests/ci-*.bats`.
- Deleting a file under `tests/` may be gated on the `ack-test-deletion` PR label; add it if asked.
- Use "Minecraft" only as a secondary title; never in the brand, domain, handles or
package names. Keep the NOT AN OFFICIAL MINECRAFT PRODUCT disclaimer on any
user-facing surface.
- Treat any stored world data as a minor's data (COPPA / GDPR-K).
- Frameworks (BMAD) are vendored from `combsmith/.github-private` or
`software-factory`; never `npx bmad-method install`.

## Org Standards

See [combsmith/.github — AGENTS.md](https://github.com/combsmith/.github/blob/main/AGENTS.md)
for org-wide development standards.

_No language-specific instruction files are deployed to `.github/instructions/` in this repo, so
the per-language links block is intentionally omitted per the Copilot Instructions Standard._
_No language-specific instruction files are deployed to `.github/instructions/` yet
(`STACK=none`); add them with the stack per the Copilot Instructions Standard._
17 changes: 14 additions & 3 deletions .github/workflows/feature-ideation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -195,9 +195,20 @@ jobs:
# its target users, and the competitive landscape. The more specific you
# are, the more useful the proposals.
project_context: |
TODO: Replace this with a description of the project and its market.
Example: "ProjectX is a [type of product] for [target user]. Competitors
include A, B, C. Key emerging trends in this space: X, Y, Z."
WorldChest is automatic backup, sync, restore and versioning for Minecraft
Bedrock worlds that live in a single fragile folder on kids' phones and
tablets; a new device, a cracked screen or a bad update wipes them with no
undo. Primary users are young Bedrock players (7-15); the buyer is their
parents, who already pay for photo backup and device insurance; secondary
users are map creators, streamers and Minecraft Education classrooms. The
freemium model targets a family subscription (~$5/month). Competitors and
substitutes: Realms (paid hosted multiplayer, not local-world preservation),
device-transfer tools such as Samsung Smart Switch (corrupt worlds), manual
ADB/.mcworld workflows. Key constraints and trends: Android 11+/iOS
owner-only app storage (tiered access: .mcworld share sheet, Shizuku power
mode, desktop companion, official Mojang API as the long-term goal), the
Minecraft Usage Guidelines (brand never contains "Minecraft"; NOT AN
OFFICIAL MINECRAFT PRODUCT disclaimer), and COPPA/GDPR-K for minors' data.
# === OPTIONAL: repo-local reputable source list ===
# Copy standards/feature-ideation-sources.md from combsmith/.github
# to .github/feature-ideation-sources.md and customise it. The reusable
Expand Down
22 changes: 19 additions & 3 deletions .github/workflows/sonarcloud.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,13 @@
#
# ADOPTING THIS WORKFLOW:
# 1. This ships verbatim into repos created from combsmith/repo-template.
# 2. Set sonar.projectKey / sonar.organization in sonar-project.properties to
# match your repo (see BOOTSTRAP.md), and add the SONAR_TOKEN repo secret.
# 2. The project key and organization are derived from the repo at run time
# (<owner>_<name> / <owner>) via `args:` on both scan steps, so a new repo
# needs no per-repo edit — add the SONAR_TOKEN repo secret and it scans into
# its own SonarCloud project (auto-provisioned on the first scan).
# sonar-project.properties carries only stack-agnostic sources/exclusions.
# If the repo is renamed, update the key on the existing SonarCloud project
# (Administration → Update Key) so its history follows the new name.
# 3. The job name `SonarCloud` is the required status check — keep it.
# 4. The scan is guarded on SONAR_TOKEN, so the job is a green no-op until the
# secret is set — a fresh repo is not blocked on day 0.
Expand All @@ -16,6 +21,9 @@
# • first scan is continue-on-error with a single retry (SonarCloud's analysis
# endpoint is occasionally flaky)
# • SHA-pin every third-party action (never a tag/branch)
# • both scan steps pass the derived -Dsonar.projectKey / -Dsonar.organization
# (a hard-coded key would make every repo cut from the template scan into
# the template's project and fail PR analysis with an unknown PR key)
# ─────────────────────────────────────────────────────────────────────────────
name: SonarCloud Analysis

Expand Down Expand Up @@ -52,10 +60,18 @@ jobs:
id: sonar
if: env.SONAR_TOKEN != ''
uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
with:
args: >-
-Dsonar.projectKey=${{ github.repository_owner }}_${{ github.event.repository.name }}
-Dsonar.organization=${{ github.repository_owner }}
continue-on-error: true
- name: Wait before SonarCloud retry
if: env.SONAR_TOKEN != '' && steps.sonar.outcome == 'failure'
run: sleep 30
- name: SonarCloud Scan (retry)
if: env.SONAR_TOKEN != '' && steps.sonar.outcome == 'failure'
uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
with:
args: >-
-Dsonar.projectKey=${{ github.repository_owner }}_${{ github.event.repository.name }}
-Dsonar.organization=${{ github.repository_owner }}
82 changes: 40 additions & 42 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,53 +6,51 @@ This repository follows the organization-wide development standards defined in
Read that file before making changes that touch CI, agent configuration, repo
settings, or labels. Repo-specific deviations, if any, are documented below.

## What this repository is

`repo-template` is the org's **template repository**: the scaffold every new
`combsmith` repo starts from via **Use this template**. It has no application
code. Its contents are the org-standard workflow stubs, baseline files, and a
bats suite that guards them.

- **Creating a repo from this template?** Follow [`BOOTSTRAP.md`](./BOOTSTRAP.md).
It is an agent-executable runbook: inputs, per-file actions, verification,
and the org-admin hand-off.
- **Changing this template?** Most files here are a distribution artifact of
`combsmith/.github` `standards/` and are regenerated by
`seed-repo-template.sh` (in `combsmith/.github-private`). Edit the standard,
not the copy. Only `tests/` and `.github/copilot-instructions.md` are owned
here outright. `README.md`, `BOOTSTRAP.md`, `AGENTS.md` and
`sonar-project.properties` are *generated* by the seeder: a change made here
must also be mirrored into the seeder's heredocs, or the next seed PR will
propose reverting it.
## Project overview

WorldChest backs up, syncs, restores and versions Minecraft Bedrock worlds for
young players on phones and tablets; parents are the buyer. The brief, the n=1
proof (232 worlds migrated S22 → S24 by hand) and the open legal and platform
questions are in
[combsmith/incubator discussion #5](https://github.com/combsmith/incubator/discussions/5).
No application code exists yet and no stack has been chosen (`STACK=none` at
bootstrap). Candidate shape from the brief: a mobile app (Android first, Bedrock
share-sheet + Shizuku power mode), a desktop companion for migrations, and a
cloud backend for storage and versioning.

## Local Development Commands

- Install: none (no application dependencies). Tests need `bats`, `shellcheck`,
`yq`, `python3` with PyYAML, and GNU bash 5 (`brew install bash bats-core shellcheck yq`;
on macOS run tests with Homebrew bash first on `PATH`, stock bash 3.2 cannot
parse the test heredocs).
- Install: none yet (no application code)
- Dev run: n/a
- Test: `bats tests/`
- Lint: `find . -path ./.git -prune -o -name '*.sh' -exec shellcheck {} +` (no
shell scripts ship today, so a bare `shellcheck *.sh` fails on the unmatched
glob; CI uses `shopt -s nullglob` for the same reason)
- Test: none yet; CI runs the org baseline (`build-and-test` shell lint, `Secret scan (gitleaks)`, `coverage`) until a stack lands
- Lint: n/a
- Typecheck: n/a

When the stack is chosen, replace this section and update `ci.yml`,
`.github/dependabot.yml`, `copilot-setup-steps.yml` and
`.github/copilot-instructions.md` per the org `AGENTS.md`
"Creating a new repository" step 3 (the template's `BOOTSTRAP.md` steps 2–4 and 7).

## Required Environment Variables

- None for local work. CI secrets (`SONAR_TOKEN`, `APP_ID`/`APP_PRIVATE_KEY`,
`GH_PAT_WORKFLOWS`, `CLAUDE_CODE_OAUTH_TOKEN`) are org-level and inherited.

## Rules specific to this template

- **Stubs are byte-exact.** `tests/*-stub.bats` compare each thin-caller
workflow against an inline snapshot of the canonical template, trailing
newline included (the committed stubs have none). Never reformat them.
- **`ci.yml` and `sonarcloud.yml` are intentionally ahead of the canonical
templates** (retry/backoff, timeouts, `persist-credentials: false`). They are
allowlisted in the template drift guard; keep their invariants in sync with
`tests/ci-*.bats` and `tests/sonarcloud-stub.bats`.
- **No `TODO`/`FIXME` in workflow files.** SonarCloud rule S1135 is enforced by
the stub tests. Reword to `Customize:`.
- **Deleting a file under `tests/`** may be gated by PR automation on the
`ack-test-deletion` label (created by the org bootstrap). Add it if asked.
- None.

## Testing

- No test suite yet. First code must arrive with tests (org TDD rule); the
`coverage` CI job stays green until tests exist and enforces from then on.

## Rules specific to this repository

- **Naming (Minecraft Usage Guidelines).** The brand is WorldChest. "Minecraft"
appears only as a secondary title ("backup for Minecraft worlds"), never in the
brand, domain, handles or package names. Every listing and site carries the
NOT AN OFFICIAL MINECRAFT PRODUCT disclaimer.
- **Minors' data.** Storing kids' worlds is COPPA / GDPR-K territory: design
parent-consent flows and data handling before any backend stores user content.
- **Frameworks are vendored, not installed.** BMAD and other agent frameworks
come from `combsmith/.github-private` or `software-factory` as `git subtree`;
never run `npx bmad-method install` here.
- **Stubs are org-managed.** The `.github/workflows/*.yml` thin-caller stubs,
`CODEOWNERS`, `CLAUDE.md`, `.gitleaks.toml` and the `.gitignore` secrets
baseline are synced by org automation; do not hand-edit them.
Loading
Loading