Imported from GAIK-project/gaik-toolkit (
AGENTS.md). Install upstream withnpx skills add GAIK-project/gaik-toolkit. Copyright stays with the author.
gaik-toolkit agent instructions
This repo is public: never commit machine-local paths, usernames or secret-store locations.
gaik-sync (keep the Solution Wizard in step with gaik)
The Solution Wizard (implementation_layer/solution_wizard/) mirrors gaik's API in a
component registry, reference cards and selection guidance. When gaik changes they drift
silently, and the wizard generates blueprints or PoCs that fail at runtime.
After a change to gaik's public surface, remind the user to run the gaik-sync skill and
offer to run it. That covers adding, removing or renaming a component, module or
behaviour-changing option; changing constructor params, the primary method or its return
shape; changing a pip extra, providers or artifact types; a new subsumption; and bumping
gaik. The skill proposes changes and edits wizard assets only after approval. A quick
read-only check: uv run python .claude/skills/gaik-sync/scripts/audit_registry.py.
Run uv sync --all-extras first, and run the audit and wizard tests through uv run.
Components swallow a missing optional dependency in __init__.py, so a missing extra
makes a class silently absent: the audit reports false removed drift and the tests skip
checks they appear to run.
agent-plugin (the published agent skills)
agent-plugin/ is installed by Claude Code, Codex, Copilot and VS Code through
.claude-plugin/marketplace.json, and its skills quote gaik's API.
- Bump
versionin bothagent-plugin/plugin.jsonandagent-plugin/.claude-plugin/plugin.jsonwith any change underagent-plugin/: each client caches an install under the version it read. implementation_layer/unit_tests/test_agent_plugin.pyfails when gaik renames a name a skill quotes; fix the skill in the same change. It checks names only, so a change in behaviour needs a read of the skill that describes it.
toolkit_demo_app on Rahti
- Deploy by pushing to the
deploy/demo-appbranch:git push origin main:deploy/demo-app. A GitHub webhook starts the BuildConfigs inopenshift/buildconfigs.yaml, and the deployments roll out when the images land.openshift/deploy.shis the local fallback. - Never
oc applythe deployment manifests inopenshift/: the live deployments carry env vars (Allas,DATABASE_URL, TTS, report-writer limits) set withoc set envthat the manifests lack, and applying them drops those. - The API image installs gaik from PyPI, not from this repository, so a gaik fix reaches
the demo app only after a release.
The demo's local uv environment uses this repository's gaik as an editable install
(
[tool.uv.sources]in itspyproject.toml), so a local run can pass on a fix that the deployed demo lacks. proxy.tsis the only auth layer in front of the FastAPI backend; every state-changing method needs a signed-in, approved user (lib/api-access.ts); the wizard routes have their own gate.
docs site (GitHub Pages)
.github/workflows/pages.yml publishes guidance_layer/website (Fumadocs, pnpm) to
https://gaik-project.github.io/gaik-toolkit/ on every push to main that touches it.
content/docs/<path>.mdx is served at /gaik-toolkit/<path>/, with no /docs segment.
Link that page, not the MDX file; the old docs host gaik-toolkit.2.rahtiapp.fi is gone.
graphify (optional)
graphify-out/ holds a committed knowledge graph. If the graphify CLI is installed,
prefer graphify query|path|explain for codebase questions and run graphify update .
after code changes. If it is not installed, use normal search and do not mention it.
Invoke /graphify only when that skill is listed. Dirty graphify-out/ files are
expected.
release certification (required before every tag and PyPI release)
- Every version tag/release requires real authenticated component tests, not only
imports, mocked calls, or the presence of API keys. Before tagging, commit the
intended release, set the wizard validated pin to the planned version, then run
uv run python scripts/release_check.py --live --version X.Y.Z. The command runs all-extras sync, offline tests, wizard tests/audit, package validation, and bounded live component checks. A passing sanitizedresults/release-check.jsonmust name the exact commit and planned version. Rerun after any tracked release change. - Set
RELEASE_PROVIDERSand explicitRELEASE_<PROVIDER>_MODELmodel/deployment IDs. Check current official model documentation/catalogs before choosing IDs; do not assume a model name in an old example is current. Every changed provider/model family and every newly added provider needs a sanitized live smoke report before tagging. The normal matrix is representative; exhaustive catalog evaluation is separate and must not automatically run on every release. - CI always requires Azure plus any providers selected in
RELEASE_PROVIDERS. Missing selected credentials, timeouts, skipped required checks, and invalid model output fail the gate. Do not turn these into a pass or bypass the gate to publish. Aitta and other optional providers can be certified locally; do not require a permanently valid Aitta token for unrelated releases. publish.ymlcalls the test workflow withrelease_gate: true; publishing depends on that complete workflow succeeding. Do not tag, upload to PyPI, or deploy the demo until the applicable certification passes. Keep credentials, raw provider errors, and personal documents out of reports; use the synthetic fixtures.
