Fullstack Explore

Fullstack Explore

Explore and understand a multi-repo fullstack workspace initialized by fullstack-init. This skill is read-only — it gathers information, answers questions about the codebase, and recommends next steps. It does NOT create branches, modify files, or make commits.

Core Principle — Read-Only Exploration

This skill MUST NOT:

• Create branches (git checkout -b)
• Commit changes (git commit)
• Push to remotes (git push)
• Create Pull Requests
• Modify any file in any repo

This skill ONLY:

• Reads workspace documentation, knowledge graphs, and source files
• Synthesizes findings and answers questions
• Recommends follow-up actions (which fullstack skill to use next)

Source-of-Truth Rule — Documents & Graphify Are Navigation, Not Answers

Documents and graphify tell you WHERE to look. Source code tells you WHAT the answer is.

Documents (from fullstack-propose/fullstack-apply) may be stale or incomplete. Graphify indexes may be out of date. Both are accelerators to find relevant code efficiently — they are NOT substitutes for reading the actual source files.

The information chain works like this:

You MUST NOT present a finding as fact until you have read the corresponding source file. When documents, graphify, and source code disagree, source code always wins. If documents or graphify claim a file exists at a path, read that file before citing it.

Prerequisites — Workspace Validation Gate

This skill MUST NOT proceed unless it confirms the current working directory is a valid fullstack workspace. Before doing ANY work, check for ALL three markers:

1. fullstack.json — workspace config created by fullstack-init
2. AGENTS.md — workspace-level AGENTS.md generated by fullstack-init
3. .agents/ — directory containing workspace agents and skills

Validation logic

Check current working directory for:
  fullstack.json  — exists?
  AGENTS.md       — exists?
  .agents/        — exists and is a directory?

ALL THREE must be present → proceed to Step 1
ANY missing → STOP and show the error below

If validation fails

Do NOT proceed with any query work. Instead, inform the user:

Workspace not detected. This skill requires a fullstack workspace initialized by fullstack-init. The current directory is missing:

• (list each missing item)

Please cd to your project workspace root and restart your AI agent there, or run fullstack-init first to set up the workspace.

Language Selection

All responses and recommendations MUST match the language of the user's prompt.

1. If the user explicitly requests a language → use that language.
2. If the user's prompt contains any Chinese characters → use Chinese.
3. Otherwise → use English (default).

Step 1 — Understand the Query

Read the user's question carefully. Classify the query type:

If the scope is unclear, ask a clarifying question before proceeding.

Step 2 — Read Workspace Context

Read these files:

1. fullstack.json — get docs_dir name and github_repos config
2. AGENTS.md — focus on:
   • Repos table: repo names, roles, tech stacks, descriptions
   • Workspace Conventions: cross-repo patterns, graphify usage
   • Directory Structure: overall layout

From the repos table, build a mental map of what each repo does.

Step 3 — Check Documents First (MANDATORY)

Before querying any repo, scan the docs directory for prior work that covers the query topic. Documents are navigation aids — they tell you which repos, files, and concepts are relevant, saving you from blind searching. Do NOT use document content as your answer; use it to know WHERE to look.

3a. Find relevant documents — GATE (check this FIRST)

Check for <docs-dir>/graphify-out/ — the docs repo can have its own knowledge graph indexing all work tracking documents. Run python3 SKILL_PATH/scripts/graphify_check.py <docs-dir> to check.

• EXISTS → go to § Docs graphify path below.
• NOT_FOUND → go to § Docs manual path below.

§ Docs graphify path

cd into the docs directory and use graphify query to find relevant documents — this is far more efficient than manually scanning directory names and section headers:

cd <docs-dir>
graphify query "which work items relate to authentication?"
graphify query "what was the conclusion of the oauth-migration spike?"
graphify query "what files were changed in the payment refactor?"
graphify query "are there any documents about API versioning?"

Graphify on the docs repo indexes all text content across documents, so it can find matches buried deep in progress.md or review.md that directory-name scanning would miss.

§ Docs manual path

Fall back to manual scanning. List the docs directory structure:

<docs-dir>/
├── changes/
│   ├── feat/<name>/        ← implementation work
│   │   ├── analysis.md     ← problem analysis, affected repos, constraints
│   │   ├── plan.md         ← implementation strategy, dependency order
│   │   ├── progress.md     ← what was done, iteration logs, test results
│   │   └── review.md       ← code review results, cross-repo consistency
│   ├── refactor/<name>/    ← same structure as feat/
│   ├── fix/<name>/         ← same structure as feat/
│   └── archive/            ← completed work (YYYY-MM-DD-<type>-<name>/)
└── AGENTS.md               ← doc directory conventions

Match work item directories against the query:

• Directory name: does <name> contain keywords from the query?
• Jira key: does the query reference a specific ticket (e.g. PROJ-123)?
• Archive: completed work lives under changes/archive/ — scan it for historical context, not just active changes/<type>/ directories.

3b. For each matching document — check relevance, not full read

Do NOT read entire documents. Scan section headers and the first paragraph of each section. Only read deeply when a section is clearly relevant.

For instance, if the query is "how does auth work?", scan plan.md for sections like "Authentication", "Auth Flow", "Identity", "Login". Only then read those specific sections.

Prioritize these high-signal sections:

3c. Assess document coverage

After scanning, categorize the document coverage:

Step 4 — Identify Repos & Choose Approach

Based on document coverage (Step 3) and the workspace repos table (Step 2).

Repos completeness rule: The workspace AGENTS.md repos table is the authoritative list of all repos. When the query involves behavior that spans multiple repos (e.g. "how does auth work"), apply the per-repo protocol to EVERY repo in the table whose role or description relates to the query topic. Documents from Step 3 may identify repos to prioritize, but they are NOT a reason to skip repos — documents may be incomplete.

4a. Full coverage — Verify mode

If documents already answer the query:

1. Extract key structural claims from the documents (file paths, module names, architecture decisions)
2. Verify those claims against the current code using graphify (fastest path) or targeted file reads:

   graphify query "does <file-path> still exist?"
   graphify query "what is the current structure of <module>?"
   

3. If code matches documents → answer from documents, note verification
4. If code has diverged → note discrepancies, then do Step 5 for the diverged areas only

4b. Partial coverage — Targeted mode

Documents provide context but the query needs more:

1. Use document findings to narrow which repos to query
2. Use document findings to form precise graphify questions
3. Go to Step 5 focusing only on the gaps

4c. No coverage — Full query mode

No relevant documents exist. Go to Step 5 for all repos identified as relevant to the query.

4d. Present repo selection (for 4b and 4c)

When documents don't fully cover the query, present your repo selection:

I'll query these repos to answer your question:

• web — likely contains the frontend routing logic
• api — likely handles the authentication endpoints

(This is based on: <workspace-AGENTS.md repos table / document X analysis.md>) Does this look right?

After user confirmation (or "just go ahead"), proceed to Step 5.

Step 5 — Gather Context from Repos

For each repo being queried, follow this per-repo protocol. Execute the protocol to completion for one repo before moving to the next.

Per-repo protocol — GATE (check this FIRST, before anything else)

Check for <repo>/graphify-out/ — run python3 SKILL_PATH/scripts/graphify_check.py <repo> to check. This script uses a direct filesystem check immune to .gitignore filtering — do NOT use Glob. Do NOT run grep or Read on source files until you have determined which path to take.

• EXISTS → go to § Graphify path below. You MUST use graphify query BEFORE touching any source files. This is not optional.
• NOT_FOUND → go to § Normal path below.

§ Graphify path

When the repo has graphify-out/, graphify query is MANDATORY. Do NOT run grep or read source files directly until you have exhausted the knowledge graph.

Graphify query strategy — narrow is better than wide.

Broad natural-language queries ("authentication, JWT validation, WebSocket auth") return thousands of community-mapped nodes and get truncated. Precision queries return focused, relevant results:

Protocol:

1. Read the repo's AGENTS.md (if it exists) — architecture conventions, design decisions, and domain terminology. Extract specific module names, class names, and function names to use in graphify queries.
2. cd into the repo directory (graphify is cwd-based).
3. Start with one precise query, not a list of keywords:

   graphify query "where is the <topic> logic implemented in <module-from-AGENTS.md>"
   

4. Check for truncation. If the output says TRUNCATED with cut nodes, you MUST take one of these actions before continuing:
   • Raise the budget: add --budget 8000 to increase the token limit
   • Narrow the scope: re-query with a more specific module/function name
   • Use a symbol name: graphify query "show me AuthManager" targets a specific symbol rather than doing a broad traversal
5. When document context is available (from Step 3), use it for targeted verification — documents give you exact file paths and module names:

   graphify query "does <path-from-doc> still exist? what does it do now?"
   graphify query "has <module-from-doc> been renamed or restructured?"
   

6. Iterate depth-first by module, not breadth-first across topics:
   • Query each relevant module fully before moving to the next
   • Don't list 5 unrelated topics in one query
7. Only AFTER exhausting graphify queries may you fall back to grep/file reads for any remaining gaps.

After graphify — verify against source code (MANDATORY). Graphify is a navigation index, not the answer. Before treating any graphify finding as truth:

• For every key claim (file path, function name, module structure), read the actual source file to confirm it matches what graphify reported.
• Graphify may be stale — if the source file's content doesn't match graphify's description, source wins. Note the discrepancy in your answer.
• Read enough of each file to understand the logic, not just the first line. An answer built on graphify alone is an answer built on potentially stale data.

§ Normal path

When the repo does NOT have graphify-out/:

1. Read the repo's AGENTS.md (if it exists) — architecture and conventions.
2. Read the repo's README.md — tech stack, build commands, overview.
3. Use grep and file reads to find relevant code. Start with:
   • Key config files (package.json, pyproject.toml, go.mod, etc.)
   • Entry points (src/, main.go, app/, etc.)
   • Files matching the query topic (grep for keywords)
4. When document context is available, use it to target specific paths rather than broad searching.

5d. Cross-reference between repos

After querying each repo, check cross-repo relationships:

• API contracts: does the frontend call endpoints the backend exposes?
• Shared types/interfaces: are there matching types across repos?
• Data flow: does the data shape change between repos?

Step 6 — Synthesize the Answer

Combine findings from documents (Step 3), graphify (Step 5), and source code (Step 5 verification) into a clear, structured response.

Answers MUST be source-code-based. Documents and graphify tell you where to look; your answer describes what you actually read in the source files. Cite specific files and line ranges.

Answer format

When documents cover the query (verify mode)

Note which findings come from documents vs. code verification:

## Answer
<direct, concise answer>

## Sources

### Document: `<docs-dir>/feat/oauth-migration/` (2025-03-15)
- plan.md: Auth flow moved to `api/src/auth/` in March 2025
- Verified: graphify confirms `api/src/auth/` is the current auth module ✓

### Code verification
- `api/src/auth/handlers.ts` — OAuth2 handlers (current, matches plan.md)
- `api/src/auth/middleware.ts` — JWT validation (current, matches plan.md)

### Discrepancies
- plan.md referenced `web/src/hooks/useAuth.ts` → graphify shows this was
  renamed to `web/src/hooks/useSession.ts` (April 2025)

When documents are partial or absent

## Answer
<direct, concise answer>

## Findings

### <repo-name> (<role>)
- Used graphify: yes / Used documents: <doc-name>
- ...

Always include

1. Direct answer — answer concisely first
2. Source attribution — where each finding came from (doc / graphify / file)
3. Staleness notes — if documents or graphify diverge from source code, flag it. Source code is the single source of truth — when document, graphify, and source disagree, source wins.
4. Key files/locations — specific paths for further exploration, verified against actual source (not graphify-reported paths alone)
5. Spot-check confirmation — explicitly note which key findings were verified by reading the actual source files

Step 7 — Recommend Next Steps

Based on the findings, recommend a concrete follow-up action:

Always give a concrete next step, not a vague suggestion:

Recommended next step: The payment flow involves changes to both web (checkout UI) and api (payment processing). This is a good candidate for fullstack-propose:

fullstack propose "Add Apple Pay to checkout"

This would create a changes/feat/add-apple-pay work item covering both repos.

Optional — Capturing Discovery (Only If Asked)

This skill is read-only by default. If the user explicitly asks to capture what you found (e.g. "record this", "write this down", "沉淀一下", "存下来"), you MAY create a draft analysis.md in the docs repo as a starting point for a future fullstack-propose:

• Target: <docs-dir>/changes/<type>/<work-name>/analysis.md (choose the type from the findings; use fullstack-propose conventions)
• Content: Objective, Current State, Findings — discovery only, no implementation plan
• Do NOT create branches, commits, or other files. Do NOT modify any project code.

This is capturing thinking, not implementing — it keeps the boundary of "read-only exploration" intact while preserving valuable findings.

Repos Outside the Workspace

If the user's query references a repository that is NOT listed in the workspace AGENTS.md repos table:

1. Ask the user if they want to add it to the workspace (via fullstack-init)
2. If yes, suggest re-running fullstack-init to discover and add the repo
3. If no, use git-repo-reader to clone and read the external repo as a one-off reference (without adding it to the workspace)