sdcorejs-explore

name

sdcorejs-explore

description

Project exploration and durable context skill. Use to understand/map a codebase, trace feature flows, find reusable components/services, refresh .sdcorejs/summary.md, recover context, set/read persona, save/read memories, harvest documentation facts, or inspect local env shape. Modes: summary-read, summary-refresh, code-map, trace-flow, env-setup, recovery, persona, memories, documentation-harvest. Runtime-localized.

Codex path resolution: Resolve ../_refs/... relative to this SKILL.md. Resolve another SDCoreJS skill by opening the sibling folder ../<skill-name>/SKILL.md.

Explore

Purpose

sdcorejs-explore is the canonical producer of project context, stack profile evidence, and safe exploration output for downstream SDCoreJS skills.

It is read-only by default. It writes only when the selected explore_action is explicitly write-approved, the target root is safe for that write, and the write is recorded in explore_context.

Use it to:

• read or refresh the canonical .sdcorejs/summary.md;
• map architecture and reusable code paths;
• trace one behavior end to end;
• inspect local setup shape without changing env files;
• recover context after a break;
• read or write the target project's persona after approval;
• read or write durable memories after approval and redaction;
• harvest documentation facts for sdcorejs-documentation.

If the user asks to judge quality or find defects, route to sdcorejs-review. If the user asks to debug, fix, or root-cause a concrete failure, route to sdcorejs-debug. If the user asks to write or run tests, route to sdcorejs-test. If the user asks to ship, verify readiness, or update dependencies, route to sdcorejs-ship. If the user asks to commit, create a PR, write a changelog, or write release notes, route to sdcorejs-git after the required gates. If the user asks to edit documentation, route to sdcorejs-documentation.

Shared Protocols

Before non-trivial exploration:

1. Read and apply ../_refs/shared/tasklist.md.
2. Read and apply ../_refs/shared/persona.md only when a project persona exists.
3. Classify explore_action before deep refs, broad scans, commands, or writes.
4. Read ../_refs/shared/project-context.md with:
   • caller_context: sdcorejs-explore;
   • context_mode: <explore_action>;
   • side_effects_allowed: false for read-only actions.
5. Current user request, current files, diffs, logs, failing tests, and command output override stored context.
6. Before presenting choices, approval gates, yes/no questions, or mode selections, read ../_refs/shared/user-choice-prompt.md.

Project-context must never recursively invoke sdcorejs-explore while sdcorejs-explore is already running.

Step 0 - Classify explore_action

Pick exactly one action before reading deep refs, running scans, or writing anything:

explore_action	Use when	Side-effect boundary
summary-read	Read the project summary, understand the project, or a read-only caller needs context	Read existing .sdcorejs/summary.md; if missing/stale, produce ephemeral summary in the response only. No writes.
summary-refresh	User explicitly asks to refresh/update/persist the summary, or a caller has write-approved context	May write .sdcorejs/summary.md after authoring-repo guard and redaction.
code-map-readonly	Map architecture, reusable paths, modules, routes, services, or code ownership	Read-only inventory. No cache writes.
trace-flow-readonly	Trace one behavior, feature, route, job, command, or test flow	Read-only trace output. No diagram/file writes unless the user separately asks.
env-setup-readonly	Explain local setup, prerequisites, scripts, env keys, or first-run steps	Read README/config/examples and output instructions. No env/config writes.
env-setup-write-approved	User explicitly approves safe env file creation from an example	May create a missing env file with placeholders only. Never overwrite existing env files.
recovery-readonly	Resume, recover context, or read where work stopped	Read summaries, tasks, docs, recent commits, and status. No auto-resume and no writes.
persona-read	Read current project persona or explanation mode	Read-only.
persona-write-approved	User explicitly asks to set/change persona or approves persona storage	May write .sdcorejs/persona.md after authoring-repo guard and redaction.
memories-read	Load durable project memory context	Read relevant memory index/frontmatter first. Bodies only on match. No writes.
memories-write-approved	User explicitly asks to remember durable knowledge	May write redacted durable memory after approval and duplicate search.
documentation-harvest-readonly	Harvest user-guide or technical-doc facts/gaps for documentation	Read-only facts for documentation renderer. No docs written by explore.

Read-only explore actions must not write .sdcorejs/*, env files, docs, tasks, source files, memory files, persona files, generated mirrors, or project artifacts. Missing or stale summary is not itself permission to write.

Write-approved actions must record the approval source, target path, reason, and write outcome in explore_context.writes.

Target Root And Authoring-Repo Guard

Resolve target root with git rev-parse --show-toplevel; if there is no git root, use the user-provided root or current directory and mark confidence.

Classify:

target_root_kind:
  target-project
  sdcorejs-agent-authoring-repo
  skill-pack-authoring-repo
  unknown

Detection signals:

• sdcorejs-agent-authoring-repo: root contains AGENTS.md, MIRROR_POLICY.md, skills/shared/workflow/explore.md, scripts/sync-skills.mjs, and package name sdcorejs-agent.
• skill-pack-authoring-repo: root contains source skills/**, ../_refs/**, generated mirrors, or mirror policy for an agent skill pack.
• target-project: root is the user's app/site/system target and not an authoring repo.
• unknown: root is ambiguous or lacks enough evidence.

When target_root_kind is sdcorejs-agent-authoring-repo or skill-pack-authoring-repo, read-only exploration is allowed, but writes to .sdcorejs/*, persona, memories, env files, docs, tasks, source files, project artifacts, or generated mirrors require explicit confirmation that this repository is the intended target. If target_root_kind is unknown, default to read-only and ask for clarification before any write.

Canonical Stack Profile Producer

Every action that inspects project shape must classify tracks, stack_profiles, profile_confidence, and profile_evidence.

Allowed tracks:

angular | nestjs | nextjs | react | node | product | design | test |
documentation | workflow | general

Allowed stack_profiles:

core-ui-angular
legacy-core-ui-angular
plain-angular
sdcorejs-nestjs
plain-nestjs
nextjs-build-website
plain-nextjs
react-vite
react-cra
react-next-generic
node-general
general

Profile rules:

• Angular: detect from angular.json, @angular/core, Angular components/modules/routes, or Angular tests. Use core-ui-angular only when @sdcorejs/angular is installed/imported/used. Use legacy-core-ui-angular only when @sd-angular/core is installed/imported or used. Use plain-angular when Angular is present without either Core UI package. Do not classify Angular as Core UI from angular.json alone.
• NestJS: detect from nest-cli.json, @nestjs/* dependencies, controllers, modules, providers, or Nest tests. Use sdcorejs-nestjs only when @sdcorejs/nestjs or strong SDCoreJS Nest conventions are detected. Use plain-nestjs otherwise. Do not assume TypeORM, PostgreSQL, Zod, SdContext, @HasPermission, or @sdcorejs/nestjs for plain NestJS.
• Next.js: detect from next.config.*, next dependency, app/, pages/, page.tsx, layout.tsx, route.ts, or Next tests. Use nextjs-build-website only with strong public-site/build-website evidence such as [locale] routes, typed i18n navigation, content/public-site structure, or prior sdcorejs-nextjs build-website context. Use plain-nextjs otherwise. Do not assume [locale], setRequestLocale, sitemap metadata, typed i18n navigation, or content folders for plain Next.js.
• React: use react-vite for Vite config plus React dependency. Use react-cra for react-scripts. Use react-next-generic when Next.js is present without build-website evidence and React-specific guidance is needed.
• Node/general: use node-general for Node projects without a stronger framework profile. Use general when no known profile is detected.

profile_evidence must cite concrete files, dependencies, imports, configs, or tests. Do not record guesses as evidence.

Scanning Discipline

Use safe, bounded scans:

• Prefer git ls-files inside git repositories.
• Fall back to targeted globs when not git-backed.
• Exclude generated/vendor/build directories by default: node_modules, dist, build, coverage, .next, .turbo, .angular, .cache, .git, playwright-report, cypress/videos, cypress/screenshots, test-results, generated clients, binary/media assets unless relevant, and generated/vendor/build output.
• Exclude generated mirrors such as codex/skills, .claude/skills, plugin/skills, plugin/_refs, and codex/skills/_refs unless the target request is specifically about skill-pack or mirror behavior.
• Do not scan .env files for values. For env setup, read example/template key names only.
• Do not dump large files. Cap large result sets and summarize counts.
• Record commands_skipped when a repo is too large, a command would be noisy, or a probe could expose secrets.
• Use path-specific probes based on detected source_roots instead of root-level grep across the whole repo when possible.

Package Manager And Command Discipline

Before suggesting or running commands:

• Detect package manager from packageManager, lockfiles, and workspace config.
• Do not mix npm, pnpm, yarn, or bun.
• Read package.json scripts before suggesting commands.
• Do not invent missing scripts.
• Do not assume npm run dev, npm run build, npm run test, npm run lint, or install commands exist.
• Do not install packages, download tools, install browsers, or start services unless explicitly requested.
• Record only commands actually run in commands_run.
• Record omitted probes in commands_skipped.

Global Secret And PII Redaction

This protocol applies to summary, recovery, env-setup, memories, trace-flow, documentation harvest, and explore_context.

Never echo or persist secret values from .env, local config, CI files, shell output, source files, stack traces, request payloads, cookies, Authorization headers, JWTs, refresh tokens, database URLs, API keys, passwords, private keys, customer PII, production data, screenshots, traces, videos, HARs, or test reports.

Never print full lines that contain likely secret values. For env/setup findings, report key names only, not values. For suspected secrets, report file path, key/category, reason, and redacted evidence such as API_KEY=[REDACTED]. If a probe would print secret values, do not run it raw. If the user provides sensitive data, summarize with placeholders and advise rotation only when appropriate.

Output Contract: explore_context

Every sdcorejs-explore response includes a compact machine-readable-ish block:

explore_context:
  source: sdcorejs-explore
  action: summary-read | summary-refresh | code-map-readonly | trace-flow-readonly | env-setup-readonly | env-setup-write-approved | recovery-readonly | persona-read | persona-write-approved | memories-read | memories-write-approved | documentation-harvest-readonly
  target_root: <path>
  target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
  tracks:
    - angular | nestjs | nextjs | react | node | product | design | test | documentation | workflow | general
  stack_profiles:
    - core-ui-angular | legacy-core-ui-angular | plain-angular | sdcorejs-nestjs | plain-nestjs | nextjs-build-website | plain-nextjs | react-vite | react-cra | react-next-generic | node-general | general
  profile_confidence: high | medium | low
  profile_evidence:
    - profile: <stack_profile>
      evidence:
        - <path or dependency or config signal>
  source_roots:
    - <path>
  files_read:
    - <path>
  commands_run:
    - command: <exact command>
      result: <short result>
      exit: <exit code>
      notes: <redacted notes>
  commands_skipped:
    - command_or_probe: <probe>
      reason: <reason>
  writes:
    - path: <path>
      reason: <reason>
      approved: true | false
  freshness:
    git_head: <sha | unknown>
    dirty: true | false | unknown
    relevant_dirty_paths:
      - <path>
    drift_commits: <number | unknown>
    summary_scope: <scope>
  redaction:
    applied: true | false
    notes: <short note>
  next_skill_hint:
    skill: <sdcorejs-* | none>
    reason: <why>

Rules:

• explore_context must not contain secrets or PII.
• writes must be empty for read-only actions.
• files_read should be summarized when huge; never flood thousands of paths.
• commands_run includes only commands actually run.
• profile_evidence cites evidence, not guesses.
• next_skill_hint may point to review/debug/test/ship/documentation/git but does not execute those workflows automatically.

Summary Actions

summary-read

Read existing .sdcorejs/summary.md when present, check freshness metadata when available, and report whether it is fresh, stale, dirty, or unknown. If missing or stale, produce an ephemeral summary in the response only. Do not write files.

Use summary-read for read-only callers such as direct review, test-plan questions, failing-output triage, recovery, debug triage, code-map requests, and any action where the user did not approve context writes.

summary-refresh

Write or refresh .sdcorejs/summary.md only when the user explicitly requested refresh/update/persist summary or the caller has write-approved context.

Before writing:

1. Run the authoring-repo guard.
2. Apply redaction.
3. Check working-tree freshness.
4. Record approval and writes in explore_context.

Missing or stale summary is not itself permission to write.

Summary frontmatter must include at least:

---
generated_at: <ISO timestamp>
generator: sdcorejs-explore
target_root: <path>
target_root_kind: target-project | sdcorejs-agent-authoring-repo | skill-pack-authoring-repo | unknown
git_head: <full sha | unknown>
dirty: true | false | unknown
relevant_dirty_paths: []
tracks: []
stack_profiles: []
profile_confidence: high | medium | low
source_roots: []
summary_scope: <scope>
package_manager: <npm | pnpm | yarn | bun | unknown>
package_manifest_hash: <hash | unknown>
package_lock_hash: <hash | unknown>
source_roots_hash: <hash | unknown>
generated_from: []
commands_run: []
commands_skipped: []
redaction_applied: true | false
---

Freshness rules:

• If relevant source/config files are dirty, mark the summary dirty or stale-for-write-sensitive downstream use.
• Relevant config includes package.json, lockfiles, angular.json, nest-cli.json, next.config.*, tsconfig*, workspace config, and detected source roots.
• If dirty state cannot be assessed because the repo is not git-backed, mark freshness as unknown rather than fresh.
• Use source_roots_hash, package_manifest_hash, or package_lock_hash when practical so package/config drift is visible without relying only on git_head.
• Summary body includes actual architecture and path evidence, not guessed SDCoreJS conventions.

code-map-readonly

Produce a read-only architecture inventory:

## Code Map - <repo>/<profile> - <timestamp>
### Detected tracks and stack_profiles
### Source roots
### Module / package inventory
### Routes / controllers / pages / jobs
### Shared UI / services / utilities
### Data boundaries and integrations
### Tests and docs nearby
### Reusable for the upcoming task
### Path conventions detected
### Unknowns

Every recommendation must cite real path evidence. Unknown or mixed-stack projects still use shared/general rules rather than SDCoreJS-specific guesses.

documentation-harvest-readonly

Documentation harvest must first detect the actual stack_profile and libraries in use. Do not assume SDCoreJS/Core UI/TypeORM/build-website conventions for plain projects.

Profile-aware harvest rules:

• Core UI harvest columns/checks apply only to core-ui-angular or legacy-core-ui-angular.
• SDCoreJS Nest, TypeORM, PostgreSQL, and permission decorator harvest applies only when those technologies are detected.
• Plain Angular harvests actual routes, UI libraries, components, forms, validators, services, state, and local component conventions.
• Plain NestJS harvests actual controllers, services, modules, DTOs, validation, database technology, persistence layer, and integration clients.
• Plain Next.js harvests actual app/pages routes, data fetching, components, server/client boundaries, route handlers, server actions, caching, and public/internal site structure.
• If the project uses Prisma, Mongoose, class-validator, Zod, Angular Material, PrimeNG, Tailwind, local components, or another library, describe actual usage instead of forcing SDCoreJS assumptions.
• Do not create false gaps based on absent SDCoreJS conventions.

Output a facts table with path evidence and unknown - reason for gaps that cannot be proven.

trace-flow-readonly

Trace actual code paths, not assumed conventions:

1. Start from the explicit user-provided entrypoint if present.
2. If no entrypoint is provided, infer candidates and ask for selection when ambiguous.
3. For frontend-to-backend traces, map UI action -> route/client call -> API endpoint -> service/domain/data layer -> response/render/update.
4. For backend traces, map controller/handler -> guards/middleware/pipes/ interceptors -> service/domain -> persistence/integration -> response/error path.
5. For Next.js, distinguish app router/pages router, server/client components, route handlers, server actions, caching, and runtime only when detected.
6. For Angular and NestJS, apply Core UI or SDCoreJS rules only when the stack_profile evidence supports them.

Do not write diagrams or files unless the user explicitly asks.

Env Setup Actions

env-setup-readonly is the default. It may read README, package manifests, lockfiles, Docker Compose, devcontainer files, env examples, and scripts. It outputs setup commands/instructions and required env key names only.

It must not create .env, .env.local, config files, or secrets by default. It must never overwrite existing env files. It must never insert real secret values. It must not install packages, download tools, or start services unless explicitly requested.

env-setup-write-approved may create a safe env file from an example only after explicit approval. Use placeholders only, preserve existing files, and record the write in explore_context.

recovery-readonly

Recovery mode is read-only by default. Read the current summary, task checkpoint, recent docs, specs/plans frontmatter, memory metadata, git status, and recent commits. Redact sensitive content from logs/reports. Do not auto-resume work. Do not auto-refresh summary unless the user explicitly asks.

End with one numbered choice prompt:

What would you like to do next?

1. Continue the previous task
2. Start a new task from current context
3. Inspect a specific document or file
4. Refresh project summary
5. Stop after this recovery summary

Reply with `1`, `2`, `3`, `4`, or `5`.

Persona Actions

persona-read reads the current persona only.

persona-write-approved requires explicit user request or approval. Do not write persona into the sdcorejs-agent authoring repo or another skill-pack authoring repo unless explicitly targeted. Do not include secrets or PII.

Persona file template:

---
persona: non-tech   # tech | non-tech
set: <YYYY-MM-DD>   # use current date
---

Persona for this project. Managed by `sdcorejs-explore (persona mode)`.
See `../_refs/shared/persona.md` for what each persona changes.

Memory Actions

memories-read loads only relevant memory index/metadata first, not every memory body.

memories-write-approved requires explicit durable knowledge and user approval. Do not save secrets, credentials, PII, transient task state, speculation, or uncertain facts as memory. Do not default every memory to angular.

Memory entries should include:

---
track: general
stack_profile: general
source_skill: sdcorejs-explore
applies_to: <scope>
created_at: <ISO timestamp>
evidence: <source>
confidence: high | medium | low
---

Supported track labels include: general, angular, nestjs, nextjs, react, product, design, test, documentation, workflow, and repo-specific labels.

Downstream Interaction

Downstream skills should treat explore_context.stack_profiles and freshness as evidence, not unquestionable truth.

• Direct read-only workflows use summary-read, existing summary reads, code-map-readonly, or ephemeral context.
• Write-approved workflows may request summary-refresh only when context artifact writes are allowed.
• If summary is stale/missing in read-only context, continue with targeted reads and report stale/missing context in explore_context.commands_skipped or freshness.
• Explore may provide next_skill_hint; it must not execute unrelated workflows automatically.

Rules

MUST DO

• Classify explore_action first.
• Keep read-only actions truly read-only.
• Use authoring-repo guard before any write.
• Produce explore_context.
• Produce stack profile evidence with concrete paths/dependencies/config.
• Redact secrets and PII globally.
• Cite real paths and line numbers where useful.
• Distill; do not dump huge file contents.
• Match the user's language at runtime.

MUST NOT

• Invent paths, scripts, stack profiles, or conventions.
• Treat stale/missing summary as write permission.
• Recursively invoke sdcorejs-explore from project-context.
• Read an entire large repo without scoping.
• Force SDCoreJS/Core UI/TypeORM/build-website assumptions onto plain projects.
• Write env files without explicit approval.
• Overwrite existing env files.
• Save transient state or secrets as memory.

Cross-References

• sdcorejs-review - quality/audit judgment after exploration
• sdcorejs-debug - concrete failing behavior and root cause
• sdcorejs-test - test authoring, execution, and TDD
• sdcorejs-ship - final verification and release readiness
• sdcorejs-git - commit, PR, changelog, release notes
• sdcorejs-documentation - documentation writing from harvested facts