project-engineering

Project Engineering

Baseline code engineering for HeyEddi Vue apps. For Flutter frontends use @flutter-engineering instead. Detects which stacks apply and adds the correct tooling: not one-size-fits-all.

Subagents (default)

Delegate scaffold/audit/test scripts to Task shell; repo discovery to explore. Main chat picks stack from audit JSON. See reference/subagents.md.

Stacks

Stack	When	Tooling added
Vue	Always for frontend work	Vite, Vitest, npm scripts, router
FastAPI	REST API backend	backend/, pytest, openapi.json, uvicorn
Firebase	Firestore / Auth client	firebase.json, rules, emulators, env template

Declare intent prefs via @heyeddi-setup (git/env + agent). Tech keys in .heyeddi/stack.json are filled by scaffold / this skill as the project evolves:

{
  "frontend": "vue",
  "backends": ["fastapi"],
  "api_port": 8090,
  "web_port": 8085,
  "git": {
    "preset": "main_staging_dev",
    "default_branch": "dev",
    "pr_base": "dev",
    "environments": { "production": "main", "staging": "staging", "dev": "dev" },
    "worktrees": false,
    "custom_workflow": null
  },
  "agent": { "commit": "ask", "push": "ask" },
  "setup": { "version": 1, "updated": "2026-09-06" }
}

{ "frontend": "vue", "backends": ["fastapi"], "api_port": 8090 }

Flutter projects: "frontend": "flutter", "web_port": 8085: see @flutter-engineering.

Or "backends": ["firebase"] or ["fastapi", "firebase"].
audit_scaffold also infers from openapi.json, firestore.rules, and .heyeddi/product.md (or legacy PRODUCT.md).

.heyeddi/ workspace

Every HeyEddi app should have a .heyeddi/ folder (created by scaffold_stack / scaffold_heyeddi):

Path	Purpose
README.md	HeyEddi intro (agents + humans workspace), free skills, heyeddi.com/humans
stack.json	Stack + prefs (@heyeddi-setup)
product.md	Product brief
design.md	DESIGN.md format: tokens, rationale, Decision log
designs/<feature>/	Handoff PNGs, briefs, wireframes
docs/	Skill-generated reports (ship, PR tracking, drift audits)

Save all skill-created documents under .heyeddi/docs/ (or the paths above) so the team can reference them later. Root PRODUCT.md / DESIGN.md / designs/ remain supported as legacy fallbacks.

Workflow

1. Prefs gate (always-on hard): @heyeddi-setup verify_setup --check before git/CI/commit assumptions; incomplete → run setup until pass.
2. audit_scaffold: per-layer JSON (vue / fastapi / firebase).
3. scaffold_stack --stack auto: fills gaps (preferred over scaffold_vue alone).
4. ensure_npm + ensure_python as needed.
5. dev_server_info: all local servers (Vue :5173, API :8090, Firebase emulators :4000).
6. Plan gate (always-on): @engineering-excellence check_engineering_plan --check before feature code; read reuse-catalog.
7. Implement features (design skills, composables, etc.).
8. write_test_stub + run_tests + run_backend_tests.
9. Change gate (always-on): audit_engineering --check (errors fail; warns advisory).
10. verify-build + pre-merge-gate.

Local dev servers

Stack	Command	URL
Vue	npm run dev	http://localhost:5173
FastAPI	cd backend && poetry run uvicorn app.main:app --reload --port 8090	http://localhost:8090/docs
Firebase	firebase emulators:start	http://localhost:4000 (UI)

Run dev_server_info for project-specific steps. Each server needs its own terminal.

References

• reference/dev-server.md: Vue
• reference/fastapi-backend.md: FastAPI
• reference/firebase-backend.md: Firebase emulators

Related skills

• backend-type-bridger: OpenAPI / Firestore → TypeScript types
• composable-patterns: FastAPI JWT vs Firebase client composables
• verify-build: production frontend build

When the task is complete: suggest next skills

When you have finished the user's request for this skill (not after every tool call or subagent phase), suggest what to run next:

1. Run:

   python .agents/skills/heyeddi/scripts/suggest_next_skill.py --current-skill project-engineering --project-root .
   

   Add --route /path if you worked a specific route.

2. Include the script's ### Next step block in your final reply. The user copies the Prompt line into chat (e.g. @heyeddi-design craft /settings).

Pass --mode shape (or craft, audit, etc.) when you know which sub-command just finished.

See @heyeddi → reference/next-skill-handoff.md.