From 880e032ba166535c39c8c12a49e23b7cbec19c91 Mon Sep 17 00:00:00 2001 From: Haylan Date: Thu, 10 Sep 2026 10:21:00 +0200 Subject: [PATCH] chore: scaffold Astro project and configure agent skills Initial commit: Astro minimal template (Node >= 22.12), agent docs (AGENTS.md/CLAUDE.md/QWEN.md), and docs/agents setup for the Gitea issue tracker via the tea CLI, triage labels, and domain docs. --- .gitignore | 27 +++++++++++++++++ .mcp.json | 8 +++++ .vscode/extensions.json | 4 +++ .vscode/launch.json | 11 +++++++ AGENTS.md | 36 ++++++++++++++++++++++ CLAUDE.md | 1 + QWEN.md | 27 +++++++++++++++++ README.md | 43 +++++++++++++++++++++++++++ astro.config.mjs | 5 ++++ docs/agents/domain.md | 51 +++++++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 56 +++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 ++++++++++ package.json | 20 +++++++++++++ public/favicon.ico | Bin 0 -> 655 bytes public/favicon.svg | 9 ++++++ src/pages/index.astro | 17 +++++++++++ tsconfig.json | 5 ++++ 17 files changed, 335 insertions(+) create mode 100644 .gitignore create mode 100644 .mcp.json create mode 100644 .vscode/extensions.json create mode 100644 .vscode/launch.json create mode 100644 AGENTS.md create mode 120000 CLAUDE.md create mode 100644 QWEN.md create mode 100644 README.md create mode 100644 astro.config.mjs create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md create mode 100644 package.json create mode 100644 public/favicon.ico create mode 100644 public/favicon.svg create mode 100644 src/pages/index.astro create mode 100644 tsconfig.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9e07131 --- /dev/null +++ b/.gitignore @@ -0,0 +1,27 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store + +# jetbrains setting folder +.idea/ + +# agent session state +.qwen/ diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..85ef2fa --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "Astro docs": { + "type": "http", + "url": "https://mcp.docs.astro.build/mcp" + } + } +} diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..22a1505 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,4 @@ +{ + "recommendations": ["astro-build.astro-vscode"], + "unwantedRecommendations": [] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..d642209 --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,11 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "command": "./node_modules/.bin/astro dev", + "name": "Development server", + "request": "launch", + "type": "node-terminal" + } + ] +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a013dd0 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,36 @@ +## Development + +When starting the dev server, use background mode: + +``` +astro dev --background +``` + +Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`. + +## Documentation + +Full documentation: https://docs.astro.build + +Consult these guides before working on related tasks: + +- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/) +- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/) +- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/) +- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/) +- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/) +- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/) + +## Agent skills + +### Issue tracker + +Issues and specs live in the Gitea repo at `git.arthurerlich.de`, managed via the `tea` CLI. See `docs/agents/issue-tracker.md`. + +### Triage labels + +Default five-label vocabulary (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context: `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file diff --git a/QWEN.md b/QWEN.md new file mode 100644 index 0000000..a3fbfcc --- /dev/null +++ b/QWEN.md @@ -0,0 +1,27 @@ +# QWEN.md + +This file provides guidance to Qwen Code when working with code in this repository. + +## Project Overview + +`php-node-renderer-playground` is an **early-stage playground/experiment repository** with no source code yet. The working tree contains only this file and `.mcp.json`, and the git repository has no commits. + +Based on the project name, the intended purpose is exploring **PHP and Node.js rendering** — e.g., how PHP and Node renderers can interoperate, share rendering logic, or be combined for server-side rendering. Nothing has been implemented yet; treat this repo as a blank slate. + +## Tools & Configuration + +- **`.mcp.json`** — Configures an MCP server for the **Astro docs** (`https://mcp.docs.astro.build/mcp`). The `mcp__Astro_docs__search_astro_docs_1e828ud` tool is available to search official Astro framework documentation. This suggests Astro (or a similar Node-based renderer) is a likely candidate for the rendering experiments. Use it when questions about Astro's rendering, SSR, or SSG behavior come up. + +## Building and Running + +No build, run, or test commands exist yet. The project has not been scaffolded. + +- TODO: Once the stack is chosen (e.g., a PHP runtime + Node/Astro renderer), document the setup and key commands here (install, dev server, build, test). +- Until then, do not assume any toolchain (composer, npm, etc.) is present — verify against files in the repo before recommending commands. + +## Development Conventions + +No conventions established yet. When code is added: + +- Follow the conventions of whichever frameworks are chosen (e.g., Astro conventions for any Node/SSR side; PSR-12 for PHP if PHP is introduced). +- Keep the playground nature in mind: this repo is for experiments, so prefer small, self-contained examples over full application scaffolding. diff --git a/README.md b/README.md new file mode 100644 index 0000000..87b813a --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# Astro Starter Kit: Minimal + +```sh +npm create astro@latest -- --template minimal +``` + +> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! + +## 🚀 Project Structure + +Inside of your Astro project, you'll see the following folders and files: + +```text +/ +├── public/ +├── src/ +│ └── pages/ +│ └── index.astro +└── package.json +``` + +Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name. + +There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components. + +Any static assets, like images, can be placed in the `public/` directory. + +## 🧞 Commands + +All commands are run from the root of the project, from a terminal: + +| Command | Action | +| :------------------------ | :----------------------------------------------- | +| `npm install` | Installs dependencies | +| `npm run dev` | Starts local dev server at `localhost:4321` | +| `npm run build` | Build your production site to `./dist/` | +| `npm run preview` | Preview your build locally, before deploying | +| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | +| `npm run astro -- --help` | Get help using the Astro CLI | + +## 👀 Want to learn more? + +Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). diff --git a/astro.config.mjs b/astro.config.mjs new file mode 100644 index 0000000..e762ba5 --- /dev/null +++ b/astro.config.mjs @@ -0,0 +1,5 @@ +// @ts-check +import { defineConfig } from 'astro/config'; + +// https://astro.build/config +export default defineConfig({}); diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..3524904 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,51 @@ +# Domain Docs + +How the engineering skills should consume this repo's domain documentation when exploring the codebase. + +## Before exploring, read these + +- **`CONTEXT.md`** at the repo root, or +- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. + +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. + +## File structure + +Single-context repo (most repos): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +Multi-context repo (presence of `CONTEXT-MAP.md` at the root): + +``` +/ +├── CONTEXT-MAP.md +├── docs/adr/ ← system-wide decisions +└── src/ + ├── ordering/ + │ ├── CONTEXT.md + │ └── docs/adr/ ← context-specific decisions + └── billing/ + ├── CONTEXT.md + └── docs/adr/ +``` + +## Use the glossary's vocabulary + +When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. + +If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). + +## Flag ADR conflicts + +If your output contradicts an existing ADR, surface it explicitly rather than silently overriding: + +> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..2bb67f0 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,56 @@ +# Issue tracker: Gitea + +Issues and specs for this repo live in the Gitea repository at +`https://git.arthurerlich.de/haylan/php-node-renderer-playground`. Use the `tea` CLI +(the official Gitea CLI, v0.15.1) for all operations. + +`tea` infers the repository from the local git remote (`origin` → this repo), so +commands are run from the repo root without `-r`. Use `-o json` for machine-readable +output (e.g. `tea issues ls -o json`). If a command can't find a login, run +`tea login` first. + +## Conventions + +- **Create an issue**: `tea issues create -t "..." -d "..."` (add `-L "label, label"` for labels) +- **Read an issue**: `tea issues --comments -o json` +- **List issues**: `tea issues ls -o json` (filters: `--state open|closed|all`, `--labels "..."`, `--keyword "..."`) +- **List issue comments**: `tea comments list ` +- **List labels**: `tea labels ls` +- **Comment on an issue**: `tea comments add "..."` +- **Add / remove labels**: `tea issues edit -L "label"` / `tea issues edit --remove-labels "label"` +- **Assign a dev**: `tea issues edit -a ` +- **Close**: `tea issues close ` +- **Reopen**: `tea issues reopen ` + +Gitea shares one number space across issues and pull requests, so a bare `#42` +may be either: resolve with `tea pulls view ` (or `tea issues -K pulls `) and +fall back to `tea issues `. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs +as feature requests; `/triage` reads this flag.)_ + +When set to `yes`, PRs run through the same labels and states as issues, using the +`tea pulls` equivalents (`tea pulls ls`, `tea pulls view `). + +## When a skill says "publish to the issue tracker" + +Create a Gitea issue in `haylan/php-node-renderer-playground` (`tea issues create`). + +## When a skill says "fetch the relevant ticket" + +Run `tea issues --comments` for the referenced number. + +## Wayfinding operations + +Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets. +Gitea has no native sub-issues or issue-dependencies API, so links are recorded in +issue bodies. + +- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. Create with `tea issues create -t "..." -d "..." -L "wayfinder:map"`. +- **Child ticket**: an issue linked to the map via a task list in the map body, with `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. +- **Blocking**: a `Blocked by: #, #` line near the top of the child body. A ticket is unblocked when every blocker is closed. +- **Frontier**: scan the map's open children (task list / `Part of`), drop any with an open blocker (per the `Blocked by` line) or an assignee; first in map order wins. +- **Claim**: assign the issue to the driving dev, the session's first write (`tea issues edit -a `). +- **Resolve**: comment the answer (`tea comments add "..."`), close the issue (`tea issues close `), then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..b716855 --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Triage Labels + +The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. + +| Label in mattpocock/skills | Label in our tracker | Meaning | +| -------------------------- | -------------------- | ---------------------------------------- | +| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue | +| `needs-info` | `needs-info` | Waiting on reporter for more information | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `wontfix` | `wontfix` | Will not be actioned | + +When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table. + +Edit the right-hand column to match whatever vocabulary you actually use. diff --git a/package.json b/package.json new file mode 100644 index 0000000..4db04e6 --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "site", + "type": "module", + "version": "0.0.1", + "engines": { + "node": ">=22.12.0" + }, + "scripts": { + "dev": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "astro": "^7.3.2" + }, + "allowScripts": { + "esbuild": true + } +} \ No newline at end of file diff --git a/public/favicon.ico b/public/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..7f48a94d16071d6c8d06478c7458ab12e675019c GIT binary patch literal 655 zcmV;A0&x9_P)Rl-XF(A`bsas&GH{e7U1}Ri zJr5jR8B2*Jd6$=$AqgTM2o2FV$WZ9|#jJ3mmpEs{jB0ps@*Kxv}=RB|IJih8Z&fqwCG`%bN0000#bW%=J zQ=IH#a_&L{B{_6Lu_3m>0bMN%+@aOmN_3G~H^8EGi>+bXO=;-|Z`uFnf==AdP z{Oj-S=ltmI=<4`LcLE*&009F@L_t(|+I`d4ZUZ3@1<*Uo7H^LoCw6-8z4wsbd;b4l zA}zMFtOw2mLX6O5Mgl}(5P=uOM4%=tnuHiuAp%(G<c=npm$Fz%eL + + + diff --git a/src/pages/index.astro b/src/pages/index.astro new file mode 100644 index 0000000..561196b --- /dev/null +++ b/src/pages/index.astro @@ -0,0 +1,17 @@ +--- + +--- + + + + + + + + + Astro + + +

Astro

+ + diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..8bf91d3 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,5 @@ +{ + "extends": "astro/tsconfigs/strict", + "include": [".astro/types.d.ts", "**/*"], + "exclude": ["dist"] +}