@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-core/skills/workflow-project-context/references/navigation-guide.md

@@ -0,0 +1,262 @@
+# Project Navigation Guide
+
+Use this guide to scan only project-entry and convention-level information. Do not deeply analyze business logic during initialization.
+
+## Recommended Scan Procedure
+
+Run the following for EACH codebase identified in Step 1:
+
+1. List files with `rg --files` from the codebase root.
+2. Ignore generated/dependency directories:
+   - `node_modules`, `dist`, `build`, `.next`, `.nuxt`, `target`, `vendor`, `.git`, `coverage`
+3. Read manifests and config first:
+   - Frontend-type codebases: `package.json`, lockfile, `vite.config.*`, `next.config.*`, `nuxt.config.*`, `angular.json`, `tsconfig.json`
+   - Backend-type codebases: `package.json`, `pom.xml`, `build.gradle`, `go.mod`, `pyproject.toml`, `requirements*.txt`, `manage.py`, `Dockerfile`, `docker-compose.yml`
+   - Extract stack profile fields from these manifests: runtime, framework, major version, key libraries, package/build tool, test framework, manifest path, dependency fingerprint, and `stack_key`
+4. Read README files only for commands and architecture notes.
+5. Inspect top-level source folders and common entry files.
+6. Identify project rule package sources (once for the whole project, not per codebase):
+   - `.planning/rules/INDEX.md`
+   - `.planning/execution-contract.md`
+   - `.planning/toolchain.md`
+   - `.planning/lessons/README.md`
+   - `.planning/milestones/`
+   - `.planning/requirements/`
+   - `.context/spec/`
+   - `.context/workflow/`
+   - `.context/lessons/README.md`
+   - root `AGENTS.md` / `CLAUDE.md`
+   - `.cursorrules` files within each codebase root
+7. Identify history model locations (once for the whole project):
+   - primary: `.planning/milestones/`, `.planning/requirements/`, `.planning/lessons/`, `.planning/*/CONTEXT.md`
+   - optional legacy: `features/`, `.context/lessons/`
+8. Stop once entry points, conventions, commands, rule package locations, and history model locations are identified for each codebase.
+
+## Scan Depth
+
+Required:
+
+- Root directories
+- Frameworks and runtimes
+- App entries
+- Routing/controller entries
+- Pages/views or API modules
+- Component conventions
+- API client or service directories
+- Models/entities and persistence directories
+- Config files
+- Dev/build/test commands
+- Stack profile and dependency fingerprint
+- Project rule package locations
+- History model locations
+
+Optional:
+
+- Auth/permission modules
+- Jobs/schedulers
+- External integrations
+- API docs
+- Style/theme system
+- Lessons or workflow checklists
+- Legacy `features/` history when present
+
+Do not inventory every page, endpoint, table, or service method.
+
+## Unknown Field Policy
+
+Use `待确认` for required fields that cannot be inferred:
+
+- Root
+- Framework
+- App entry
+- Router/controllers
+- Dev/build/test commands
+
+For optional fields that are not found, prefer a short note in `Missing Information` instead of filling every cell with `待确认`.
+
+If a whole area does not apply, mark status as `不适用`.
+
+## Frontend Detection
+
+Common files:
+
+- `package.json`: scripts, dependencies, package manager hints
+- `vite.config.*`: Vite
+- `next.config.*`: Next.js
+- `nuxt.config.*`: Nuxt
+- `angular.json`: Angular
+- `src/main.ts`, `src/main.tsx`: Vite Vue/React entry
+- `app/layout.tsx`, `app/page.tsx`, `pages/_app.tsx`: Next.js entry/router
+
+Framework hints:
+
+| Framework | Entries | Router | Pages | Component Conventions |
+|-----------|---------|--------|-------|-----------------------|
+| React + Vite | `src/main.tsx` | `src/router`, `src/App.tsx` | `src/pages` | `src/components`, `src/pages/**/components`, `src/hooks`, `src/layouts` |
+| Next.js | `app/layout.tsx`, `pages/_app.tsx` | `app/`, `pages/` | `app/`, `pages/` | `components/`, `app/**/_components`, `hooks/` |
+| Vue + Vite | `src/main.ts` | `src/router/index.ts` | `src/views`, `src/pages` | `src/components`, `src/views/**/components`, `src/composables`, `src/layouts` |
+| Nuxt | `app.vue` | `pages/` | `pages/` | `components/`, `composables/`, `layouts/` |
+| Angular | `src/main.ts` | `app-routing.module.ts` | feature modules | `src/app/shared/components`, `src/app/features/**/components`, `src/app/core`, `src/app/shared` |
+
+Frontend navigation fields:
+
+- Root
+- Framework
+- Stack slot: Common Web, React, Next.js, Vue, or Unknown
+- Package manager
+- App entry
+- Router
+- Pages / views
+- API client
+- State management
+- Auth / permission
+- Styles / theme
+- Env config
+- Dev/build/test commands
+- Frontend rule sources such as `.context/spec/frontend/`, `.context/spec/design/`, `.planning/rules/`, `.planning/toolchain.md`, and lessons
+
+## Frontend Stack Slot Detection
+
+Record the strongest detected slot:
+
+| Slot | Detection |
+|------|-----------|
+| Next.js | `next` dependency, `next.config.*`, `app/`, or `pages/` with Next conventions |
+| React | `react` dependency, `src/main.tsx`, `src/App.tsx`, JSX/TSX entry, Vite React plugin |
+| Vue | `vue` dependency, `.vue` files, Vue Vite plugin, `vue.config.*` |
+| Common Web | Browser frontend with no supported framework-specific slot |
+| Unknown | Not enough evidence |
+
+For Next.js, record both `Next.js` and React compatibility in notes because the frontend tech spec loads both `react.md` and `next.md`.
+
+Component convention fields:
+
+- Common components
+- Page components
+- Layout components
+- Form components
+- Table/list components
+- Business components
+- UI library wrappers
+- Hooks/composables
+- Component styles
+
+## Backend Detection
+
+Common files:
+
+- `pom.xml`, `build.gradle`, `*Application.java`: Spring Boot
+- `package.json`, `src/main.ts`, `*.module.ts`: NestJS
+- `src/app.ts`, `src/server.ts`, `index.js`: Express/Koa
+- `manage.py`, `settings.py`, `urls.py`: Django
+- `main.py`, `app/main.py`: FastAPI
+- `go.mod`, `main.go`: Go
+
+Framework hints:
+
+| Framework | Entry | Routes / Controllers | Services | Models / Persistence |
+|-----------|-------|----------------------|----------|----------------------|
+| Spring Boot | `*Application.java` | `controller/` | `service/` | `entity/`, `domain/`, `model/`, `repository/`, `mapper/`, `dao/` |
+| NestJS | `src/main.ts` | `*.controller.ts` | `*.service.ts` | `*.entity.ts`, `entities/`, `prisma/` |
+| Express/Koa | `src/app.ts`, `src/server.ts`, `index.js` | `routes/`, `controllers/` | `services/` | `models/`, `repositories/` |
+| Django | `manage.py` | `urls.py`, `views.py` | app services if present | `models.py`, `migrations/` |
+| FastAPI | `main.py`, `app/main.py` | `routers/` | `services/` | `models/`, `schemas/`, `alembic/` |
+| Go Gin/Echo | `main.go` | `router/`, `handler/` | `service/` | `model/`, `repository/` |
+
+Backend navigation fields:
+
+- Root
+- Framework
+- Runtime / language
+- App entry
+- Routes / controllers
+- Services
+- Models / entities
+- Repository / DAO / mapper
+- Database migrations
+- Auth / permission
+- Jobs / schedulers
+- External integrations
+- API docs
+- Env config
+- Dev/build/test commands
+
+## Command Extraction
+
+Prefer scripts already defined in:
+
+- `package.json`
+- `Makefile`
+- `pnpm-workspace.yaml`
+- `pom.xml` / Gradle tasks
+- `README.md`
+- `docker-compose.yml`
+
+If command is not obvious, write `待确认`.
+
+## Project Rule Package Detection
+
+Record rule package locations without copying their full contents during initialization.
+
+Common sources:
+
+| Source | Purpose |
+|--------|---------|
+| `.planning/rules/INDEX.md` | Project rule index used by workflow skills |
+| `.planning/execution-contract.md` | Layer order, TDD strategy, codegen and verification gates |
+| `.planning/toolchain.md` | Build, test, lint, mock, migration, and codegen commands |
+| `.planning/lessons/README.md` | Project lessons maintained by workflow |
+| `.planning/milestones/` | Primary milestone/history records for this workflow |
+| `.planning/requirements/` | Current or historical requirement baselines |
+| `.context/spec/index.md` | Generated or existing technical spec registry |
+| `.context/spec/stacks/` | Stack-level technical specs generated from stack profiles |
+| `.context/spec/frontend/` / `.context/spec/backend/` | Codebase-specific technical specs |
+| `.context/workflow/` | Existing workflow gates such as TDD and verification |
+| `.context/lessons/README.md` | Existing lessons from project work |
+| `AGENTS.md` / `CLAUDE.md` | Root agent instructions |
+
+If both `.planning/rules/` and `.context/spec/` exist, record both. Do not merge them during initialization.
+
+## Generated Context Spec Checks
+
+When project initialization generates `.context/spec/`, verify:
+
+- Every local/scannable codebase has a stack profile with `stack_key`, manifest path, and dependency fingerprint.
+- Every unique `stack_key` has exactly one `.context/spec/stacks/{stack_key}.md`.
+- Every frontend-type codebase has `.context/spec/frontend/{name}.md`.
+- Every backend/service-type codebase has `.context/spec/backend/{name}.md`.
+- `.context/spec/index.md` maps each codebase to its stack spec, codebase spec, and navigation file.
+- Generated specs include version metadata and regeneration triggers.
+- Stack specs contain stack-level guidance only; codebase-local paths and route/module names belong in codebase specs.
+
+## History Model Detection
+
+This workflow uses `.planning` artifacts as the primary long-term memory. Do not assume outbound-call style `features/*.spec.md` history exists.
+
+| Source | Role |
+|--------|------|
+| `.planning/milestones/` | Archived milestones and delivery summaries |
+| `.planning/requirements/` | Requirement baselines and requirement decisions |
+| `.planning/lessons/` | Cross-milestone lessons |
+| `.planning/*/CONTEXT.md` | Phase/session decisions and handoff context |
+| `features/` | Optional legacy feature docs if the target project already has them |
+| `.context/lessons/` | Optional legacy/project-rule lessons |
+
+Record whether each primary source exists. Label legacy sources as legacy/project-rule evidence rather than the default history model.
+
+## Final Review Checklist
+
+- All codebase locations are recorded in the Codebase Registry.
+- Nonexistent or remote-only locations are marked pending.
+- Each codebase has a navigation file at `.planning/navigation/{name}.md`.
+- Frameworks are recorded or `待确认` for each codebase.
+- Entry points and key directories are recorded or `待确认` for each codebase.
+- Frontend-type codebases have component conventions.
+- Backend-type codebases have layer conventions.
+- Dev/build/test commands are recorded or `待确认` for each codebase.
+- Project rule package sources are recorded when present.
+- History model sources are recorded, with `.planning` sources primary and legacy sources labeled.
+- `STATE.md` includes current step, completed steps, pending steps, blockers, and next action.
+- `INDEX.md` includes Codebase Registry and downstream read contract.
+- Initialization quality is marked as `complete`, `partial`, `pending`, or `not_applicable`.
+- Requirements and roadmap files are not generated unless explicitly requested.