Mikael Hugo a611cd5792 feat: introduce repo-vcs skill and add JSDoc annotations across core modules

- Add repository-vcs-context.ts to detect and inject VCS context (Git/Jujutsu)
  into the agent system prompt; wire in repo-vcs bundled skill trigger
- Add src/resources/skills/repo-vcs/ skill for commit, push, and safe-push workflows
- Add JSDoc Purpose/Consumer annotations to app-paths, bundled-extension-paths,
  errors, extension-discovery, extension-registry, headless-types, headless, and traces
- Add justfile and just to flake.nix devShell
- Fill out new-user-onboarding.md spec (Draft) and core-beliefs.md (Status: Accepted)
- Add notification-event-model.md design doc and notification-source-hygiene.md spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-01 21:36:32 +02:00

1.7 KiB

Raw Permalink Blame History

New User Onboarding

Status: Draft

User Problem

New users need to understand that Singularity Forge is the current product, where decisions live, and how to make changes without breaking repo memory.

Goals

Orient a new user from the root docs in under a few minutes.
Make the canonical homes for specs, design docs, plans, generated references, and records obvious.
Explain what verification is expected before closing work.

Non-Goals

Do not define a marketing journey.
Do not choose a runtime or frontend framework in this spec.
Do not require a production onboarding flow before the product surface exists.

First-Run Experience

Until a runtime exists, onboarding is documentation-based:

Start with root AGENTS.md.
Read ARCHITECTURE.md for current state, boundaries, and invariants.
Read docs/PLANS.md and docs/exec-plans/active/ for current work.
Read docs/QUALITY_SCORE.md, docs/RELIABILITY.md, and docs/SECURITY.md before behavior changes.
Use docs/RECORDS_KEEPER.md after meaningful changes.

Success Criteria

The user can identify the canonical doc for a product decision, architecture decision, active plan, generated artifact, or records note.
The user can name the command or eval expected to prove their change.
The user can tell that active CLI source is in /home/mhugo/code/singularity-forge, while this singularity-foundry checkout is legacy context.

Failure States

A new user infers production behavior from placeholders.
A source change happens without a spec, plan, test, or eval.
A durable decision is left only in chat or a temporary note.

Verification

find . -maxdepth 4 -type f -name '*.md' -print

1.7 KiB Raw Permalink Blame History