# Fullstack Explore

> Read-only knowledge exploration across a multi-repo fullstack workspace — answer architecture questions, locate implementations, explain cross-repo relationships, and recommend next steps. No branches, no commits, no file modifications. Information is gathered in order of token efficiency: workspace documents (human summaries) → graphify knowledge graphs (structured queries) → direct file reading (raw code). Trigger: "fullstack explore", "fullstack query", "全栈探索", "全栈查询", "工作区查询", "workspace query"; ALSO when the user asks discovery questions inside a fullstack workspace — "what does this workspace do", "这个工作区是做什么的", "which repo handles X", "哪个仓库负责X", "explain the architecture", "讲解架构", "where is the code for Y", "Y的代码在哪里", "how does X work across repos", "which repos are involved in Z", "Z涉及哪些仓库", "告诉我这个项目的结构", "这个项目的技术栈是什么".

- Skill: `jie-meng/fullstack-explore` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jie-meng/fullstack-explore`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jie-meng/fullstack-explore/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: Apache-2.0
- Author: jie-meng (https://skillmd.com/u/jie-meng)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jie-meng/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:

| Step | Source | Purpose |
|------|--------|---------|
| **1. Navigate** | Docs repo (work tracking docs) | Human summaries that tell you *what* to look for and *which repos/files* are relevant |
| **2. Navigate** | Graphify knowledge graphs | Structured code index that tells you *where* modules, functions, and relationships live |
| **3. Verify & Answer** | Source files (read) | **The only authoritative source.** Every key claim in your answer MUST be confirmed by reading the actual source code |

**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:

| Query type | Description | Typical scope |
|------------|-------------|---------------|
| **Architecture overview** | "What does this workspace do?", "Explain the architecture" | All repos (high-level) |
| **Role discovery** | "Which repo handles user auth?", "Where is the payment logic?" | Target repo + callers/callees |
| **Implementation lookup** | "How is X implemented?", "Show me the code for Y" | Specific repos containing the feature |
| **Cross-repo flow** | "How does a request flow from the frontend to the database?" | Full chain of repos |
| **Tech stack inquiry** | "What tech stack does this project use?" | All repos (surface-level) |
| **Dependency tracking** | "Which repos depend on Z?", "What happens if I change X?" | All repos referencing the target |

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:

| Document | Priority sections |
|----------|------------------|
| `analysis.md` | Problem statement, Affected repos, Constraints |
| `plan.md` | Affected repos table, Implementation strategy, Success Criteria |
| `progress.md` | Round summaries, "What was implemented", Key file changes |
| `review.md` | Evidence table, Cross-repo consistency findings (skip per-file review blocks) |

### 3c. Assess document coverage

After scanning, categorize the document coverage:

| Coverage | Description | Action |
|----------|-------------|--------|
| **Full** | Document answers the query entirely | Go to Step 4 (verify mode) |
| **Partial** | Document provides context but not the full answer | Go to Step 5 with document context loaded |
| **None** | No relevant documents found | Skip to Step 5 directly |

## 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:

| Instead of | Try this | Why |
|-----------|----------|-----|
| `graphify query "how does auth work in the codebase"` | `graphify query "what does the auth_manager module handle"` | Narrow scope to a specific module |
| `graphify query "authentication, JWT validation, WebSocket auth"` | `graphify query "where is JWT token signing implemented"` | One precise question per query |
| `graphify query "what are all the WebSocket handlers"` | `graphify query "show me the WebSocket authentication flow"` | Ask for a flow, not a list |

**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:

```markdown
## 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

```markdown
## 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:

| Scenario | Recommendation |
|----------|---------------|
| Query revealed a straightforward change | Suggest `fullstack-propose` with specific work scope (planner subagent will analyze, developer will implement, reviewer will validate) |
| Uncertainty remains, needs prototyping | Suggest `fullstack-propose` (deep mode) to validate assumptions |
| Work is done, needs closing | Suggest `fullstack-archive` |
| Workspace setup is incomplete or outdated | Suggest re-running `fullstack-init` (regenerates AGENTS.md, agents, and symlinks) |
| Repos missing graphify would benefit from it | Suggest running `graphify` to build knowledge graphs |
| Documents are stale and should be updated | Suggest opening a docs update work item |
| Answer is complete, no follow-up needed | State that and stop |

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)