# Project Engineering

> Ensures HeyEddi projects have the right engineering stack: Vue (Vite/Vitest), FastAPI backend, or Firebase tooling. Audits gaps, scaffolds as needed, installs deps, runs tests, documents local dev servers. Use when the repo is thin or before design/feature work on any HeyEddi app.

- Skill: `heyeddi-com/project-engineering-2` (Agent Skill, multi-file: 62 files)
- Install (CLI): `npx skillmds@latest add heyeddi-com/project-engineering-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/heyeddi-com/project-engineering-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: HeyEddi-com (https://skillmd.com/u/heyeddi-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/heyeddi-com/project-engineering-2

---


# 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 in `.heyeddi/stack.json`:

```json
{ "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](https://heyeddi.com/humans) |
| `stack.json` | Declared stacks |
| `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. **`audit_scaffold`**: per-layer JSON (vue / fastapi / firebase).
2. **`scaffold_stack --stack auto`**: fills gaps (preferred over `scaffold_vue` alone).
3. **`ensure_npm`** + **`ensure_python`** as needed.
4. **`dev_server_info`**: all local servers (Vue :5173, API :8090, Firebase emulators :4000).
5. Implement features (design skills, composables, etc.).
6. **`write_test_stub`** + **`run_tests`** + **`run_backend_tests`**.
7. **`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:

   ```bash
   python .agents/skills/heyeddi-orchestrator/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-orchestrator` → `reference/next-skill-handoff.md`.