@c4a/context 0.6.0-alpha.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -0
- package/contracts.d.ts +31 -0
- package/docs/README.md +39 -0
- package/docs/getting-started.md +320 -0
- package/docs/guides/agent-dialogue.md +325 -0
- package/docs/guides/agent-guide.md +313 -0
- package/docs/guides/package-outputs.md +171 -0
- package/docs/reference/package-templates.md +274 -0
- package/docs/reference/project-api.md +326 -0
- package/docs/reference/template-variables.md +225 -0
- package/documentEvidence.d.ts +17 -0
- package/index.d.ts +55 -0
- package/index.js +11810 -0
- package/package.json +11 -0
- package/phases.d.ts +169 -0
- package/sources.d.ts +138 -0
- package/templates/package-templates/kb/AGENTS.md +31 -0
- package/templates/package-templates/kb/skills/knowledge-query/SKILL.md +204 -0
- package/templates/package-templates/kb/wikis/index.md +43 -0
- package/templates/package-templates/llms/llms.txt +9 -0
package/package.json
ADDED
package/phases.d.ts
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { type EntityStatus, type FileCaptureProcessorDefinition, type KnowledgeCollection, type MarkdownTransform, type PackageKind, type PackageSelectDefinition, type DocumentMainlineCollection } from "./contracts.js";
|
|
2
|
+
import { DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION } from "./documentEvidence.js";
|
|
3
|
+
import type { DocumentSourceDefinition, DocumentSourceType, FileSourceDefinition, FileSourceReference, LarkSourceDefinition, LarkSourceReference, RepoProjectSourceDefinition, SourceCollectionReference, SourceDefinition } from "./sources.js";
|
|
4
|
+
export type PhaseResourceReference = {
|
|
5
|
+
kind: "source";
|
|
6
|
+
source: SourceDefinition | SourceCollectionReference;
|
|
7
|
+
} | {
|
|
8
|
+
kind: "source.snapshot";
|
|
9
|
+
source: DocumentSourceDefinition;
|
|
10
|
+
sourceType: DocumentSourceType;
|
|
11
|
+
path: string;
|
|
12
|
+
} | {
|
|
13
|
+
kind: "unapproved.entities";
|
|
14
|
+
path: string;
|
|
15
|
+
collection?: KnowledgeCollection;
|
|
16
|
+
status?: EntityStatus;
|
|
17
|
+
} | {
|
|
18
|
+
kind: "unapproved.structure";
|
|
19
|
+
path: "unapproved/structure.yaml";
|
|
20
|
+
profileCollection?: DocumentMainlineCollection;
|
|
21
|
+
status?: "draft" | "confirmed" | "frozen";
|
|
22
|
+
} | {
|
|
23
|
+
kind: "knowledge.collection";
|
|
24
|
+
path: string;
|
|
25
|
+
collection: KnowledgeCollection;
|
|
26
|
+
status: "approved";
|
|
27
|
+
} | {
|
|
28
|
+
kind: "knowledge.approved";
|
|
29
|
+
path: "knowledge";
|
|
30
|
+
select?: PackageSelectDefinition;
|
|
31
|
+
} | {
|
|
32
|
+
kind: "package.template";
|
|
33
|
+
path: string;
|
|
34
|
+
} | {
|
|
35
|
+
kind: "review.payload";
|
|
36
|
+
path: string;
|
|
37
|
+
} | {
|
|
38
|
+
kind: "dist.package";
|
|
39
|
+
path: string;
|
|
40
|
+
packageName: string;
|
|
41
|
+
packageKind: PackageKind;
|
|
42
|
+
};
|
|
43
|
+
export type ContextPhaseContext = {
|
|
44
|
+
ensureSources: (options?: {
|
|
45
|
+
source?: SourceDefinition;
|
|
46
|
+
}) => Promise<void>;
|
|
47
|
+
extract: {
|
|
48
|
+
ts: (options: ExtractTsPhaseDefinition) => Promise<void>;
|
|
49
|
+
};
|
|
50
|
+
review: {
|
|
51
|
+
html: (options: ReviewValidityPhaseDefinition) => Promise<void>;
|
|
52
|
+
};
|
|
53
|
+
};
|
|
54
|
+
export type ContextPhase = (ctx: ContextPhaseContext) => unknown | Promise<unknown>;
|
|
55
|
+
export type ExtractTsPhaseDefinition = {
|
|
56
|
+
kind: "phase.extract.ts";
|
|
57
|
+
id: string;
|
|
58
|
+
reads: readonly PhaseResourceReference[];
|
|
59
|
+
writes: readonly PhaseResourceReference[];
|
|
60
|
+
source: RepoProjectSourceDefinition;
|
|
61
|
+
collection: "codegraph";
|
|
62
|
+
include: readonly string[];
|
|
63
|
+
exportedOnly: boolean;
|
|
64
|
+
transform?: MarkdownTransform | readonly MarkdownTransform[];
|
|
65
|
+
out: {
|
|
66
|
+
kind: "codegraph-entities";
|
|
67
|
+
candidateFile: string;
|
|
68
|
+
approvedPagesDir: string;
|
|
69
|
+
initialStatus: "draft";
|
|
70
|
+
};
|
|
71
|
+
};
|
|
72
|
+
export type CaptureFilePhaseDefinition = {
|
|
73
|
+
kind: "phase.capture.file";
|
|
74
|
+
id: string;
|
|
75
|
+
reads: readonly PhaseResourceReference[];
|
|
76
|
+
writes: readonly PhaseResourceReference[];
|
|
77
|
+
source: FileSourceDefinition | FileSourceReference;
|
|
78
|
+
processors?: readonly FileCaptureProcessorDefinition[];
|
|
79
|
+
};
|
|
80
|
+
export type CaptureLarkPhaseDefinition = {
|
|
81
|
+
kind: "phase.capture.lark";
|
|
82
|
+
id: string;
|
|
83
|
+
reads: readonly PhaseResourceReference[];
|
|
84
|
+
writes: readonly PhaseResourceReference[];
|
|
85
|
+
source: LarkSourceDefinition | LarkSourceReference;
|
|
86
|
+
};
|
|
87
|
+
export type AlignProsePhaseDefinition = {
|
|
88
|
+
kind: "phase.align.prose";
|
|
89
|
+
id: string;
|
|
90
|
+
reads: readonly PhaseResourceReference[];
|
|
91
|
+
writes: readonly PhaseResourceReference[];
|
|
92
|
+
source: DocumentSourceDefinition;
|
|
93
|
+
sourceType?: DocumentSourceType;
|
|
94
|
+
collection: DocumentMainlineCollection;
|
|
95
|
+
};
|
|
96
|
+
export type CompileProsePhaseDefinition = {
|
|
97
|
+
kind: "phase.compile.prose";
|
|
98
|
+
id: string;
|
|
99
|
+
reads: readonly PhaseResourceReference[];
|
|
100
|
+
writes: readonly PhaseResourceReference[];
|
|
101
|
+
source: DocumentSourceDefinition;
|
|
102
|
+
sourceType?: DocumentSourceType;
|
|
103
|
+
collection: DocumentMainlineCollection;
|
|
104
|
+
schemaVersion: typeof DOCUMENT_COMPILE_ACTION_SCHEMA_VERSION;
|
|
105
|
+
};
|
|
106
|
+
export type ReviewValidityScope = {
|
|
107
|
+
kind: "collection";
|
|
108
|
+
collection: KnowledgeCollection;
|
|
109
|
+
} | {
|
|
110
|
+
kind: "all";
|
|
111
|
+
};
|
|
112
|
+
export type ReviewValidityPhaseDefinition = {
|
|
113
|
+
kind: "phase.review.validity";
|
|
114
|
+
id: string;
|
|
115
|
+
reads: readonly PhaseResourceReference[];
|
|
116
|
+
writes: readonly PhaseResourceReference[];
|
|
117
|
+
collection?: KnowledgeCollection;
|
|
118
|
+
scope: ReviewValidityScope;
|
|
119
|
+
status: "draft";
|
|
120
|
+
payload: string;
|
|
121
|
+
decisions: readonly ["approved", "rejected"];
|
|
122
|
+
};
|
|
123
|
+
export type CustomPhaseDefinition = {
|
|
124
|
+
kind: "phase.custom";
|
|
125
|
+
id: string;
|
|
126
|
+
reads: readonly PhaseResourceReference[];
|
|
127
|
+
writes: readonly PhaseResourceReference[];
|
|
128
|
+
run: ContextPhase;
|
|
129
|
+
};
|
|
130
|
+
export type PhaseDefinition = ExtractTsPhaseDefinition | CaptureFilePhaseDefinition | CaptureLarkPhaseDefinition | AlignProsePhaseDefinition | CompileProsePhaseDefinition | ReviewValidityPhaseDefinition | CustomPhaseDefinition;
|
|
131
|
+
export declare function mdxJsonDocs(options?: {
|
|
132
|
+
include?: readonly string[];
|
|
133
|
+
documentExtensions?: readonly string[];
|
|
134
|
+
routeMetadataFile?: string;
|
|
135
|
+
}): FileCaptureProcessorDefinition;
|
|
136
|
+
export declare const captureFile: (definition: {
|
|
137
|
+
source: FileSourceDefinition | FileSourceReference;
|
|
138
|
+
processor?: FileCaptureProcessorDefinition;
|
|
139
|
+
processors?: readonly FileCaptureProcessorDefinition[];
|
|
140
|
+
}) => CaptureFilePhaseDefinition;
|
|
141
|
+
export declare const captureLark: (definition: {
|
|
142
|
+
source: LarkSourceDefinition | LarkSourceReference;
|
|
143
|
+
}) => CaptureLarkPhaseDefinition;
|
|
144
|
+
export declare const alignProse: (definition: {
|
|
145
|
+
source: DocumentSourceDefinition;
|
|
146
|
+
collection: DocumentMainlineCollection;
|
|
147
|
+
}) => AlignProsePhaseDefinition;
|
|
148
|
+
export declare const compileProse: (definition: {
|
|
149
|
+
source: DocumentSourceDefinition;
|
|
150
|
+
collection: DocumentMainlineCollection;
|
|
151
|
+
}) => CompileProsePhaseDefinition;
|
|
152
|
+
export declare const extractTs: (definition: {
|
|
153
|
+
source: RepoProjectSourceDefinition;
|
|
154
|
+
collection: "codegraph";
|
|
155
|
+
include?: readonly string[];
|
|
156
|
+
exportedOnly?: boolean;
|
|
157
|
+
transform?: MarkdownTransform | readonly MarkdownTransform[];
|
|
158
|
+
}) => ExtractTsPhaseDefinition;
|
|
159
|
+
export declare const reviewValidity: (definition: {
|
|
160
|
+
collection: KnowledgeCollection;
|
|
161
|
+
payload?: string;
|
|
162
|
+
} | {
|
|
163
|
+
scope: "all";
|
|
164
|
+
payload?: string;
|
|
165
|
+
}) => ReviewValidityPhaseDefinition;
|
|
166
|
+
export declare const customPhase: (id: string, run: ContextPhase, io?: {
|
|
167
|
+
reads?: readonly PhaseResourceReference[];
|
|
168
|
+
writes?: readonly PhaseResourceReference[];
|
|
169
|
+
}) => CustomPhaseDefinition;
|
package/sources.d.ts
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
export type SourceType = "repo" | "file" | "lark";
|
|
2
|
+
export type DocumentSourceType = Extract<SourceType, "file" | "lark">;
|
|
3
|
+
export declare const DEFAULT_REPO_SOURCES_REGISTRY_PATH = "sources/repo/index.yaml";
|
|
4
|
+
export declare const DEFAULT_FILE_SOURCES_REGISTRY_PATH = "sources/file/index.yaml";
|
|
5
|
+
export declare const DEFAULT_LARK_SOURCES_REGISTRY_PATH = "sources/lark/index.yaml";
|
|
6
|
+
export type RepoSourceDefinition = {
|
|
7
|
+
kind: "source.repo";
|
|
8
|
+
id: string;
|
|
9
|
+
name: string;
|
|
10
|
+
local?: string;
|
|
11
|
+
subpath?: string;
|
|
12
|
+
materializedAt: string;
|
|
13
|
+
git: {
|
|
14
|
+
remote: string;
|
|
15
|
+
ref: string;
|
|
16
|
+
};
|
|
17
|
+
};
|
|
18
|
+
export type FileSourceDefinition = {
|
|
19
|
+
kind: "source.file";
|
|
20
|
+
id: string;
|
|
21
|
+
name: string;
|
|
22
|
+
local?: string;
|
|
23
|
+
materializedAt: string;
|
|
24
|
+
include?: readonly string[];
|
|
25
|
+
snapshot?: {
|
|
26
|
+
manifest: string;
|
|
27
|
+
};
|
|
28
|
+
};
|
|
29
|
+
export type LarkSourceDefinition = {
|
|
30
|
+
kind: "source.lark";
|
|
31
|
+
id: string;
|
|
32
|
+
name: string;
|
|
33
|
+
materializedAt: string;
|
|
34
|
+
url?: string;
|
|
35
|
+
docToken?: string;
|
|
36
|
+
wikiToken?: string;
|
|
37
|
+
title?: string;
|
|
38
|
+
snapshot?: {
|
|
39
|
+
manifest: string;
|
|
40
|
+
};
|
|
41
|
+
};
|
|
42
|
+
export type TypedSourceReference<TType extends SourceType = SourceType> = {
|
|
43
|
+
kind: "source.ref";
|
|
44
|
+
type: TType;
|
|
45
|
+
name: string;
|
|
46
|
+
materializedAt: string;
|
|
47
|
+
};
|
|
48
|
+
export type RegistrySourceReference = {
|
|
49
|
+
kind: "source.ref";
|
|
50
|
+
name: string;
|
|
51
|
+
materializedAt: string;
|
|
52
|
+
};
|
|
53
|
+
export type SourceReference<TType extends SourceType = SourceType> = TypedSourceReference<TType>;
|
|
54
|
+
export type RepoSourceReference = RegistrySourceReference | TypedSourceReference<"repo">;
|
|
55
|
+
export type FileSourceReference = RegistrySourceReference | TypedSourceReference<"file">;
|
|
56
|
+
export type LarkSourceReference = RegistrySourceReference | TypedSourceReference<"lark">;
|
|
57
|
+
export type DocumentSourceReference = FileSourceReference | LarkSourceReference;
|
|
58
|
+
export type SourceCollectionReference<TType extends SourceType = SourceType> = {
|
|
59
|
+
kind: "source.collection";
|
|
60
|
+
type: TType;
|
|
61
|
+
};
|
|
62
|
+
export type RepoSourceRegistryEntry = {
|
|
63
|
+
id: string;
|
|
64
|
+
name: string;
|
|
65
|
+
local?: string;
|
|
66
|
+
subpath?: string;
|
|
67
|
+
materializedAt: string;
|
|
68
|
+
remote: string;
|
|
69
|
+
ref: string;
|
|
70
|
+
};
|
|
71
|
+
export type FileSourceRegistryEntry = {
|
|
72
|
+
id: string;
|
|
73
|
+
name: string;
|
|
74
|
+
local?: string;
|
|
75
|
+
materializedAt: string;
|
|
76
|
+
include?: readonly string[];
|
|
77
|
+
snapshot?: {
|
|
78
|
+
manifest: string;
|
|
79
|
+
};
|
|
80
|
+
};
|
|
81
|
+
export type LarkSourceRegistryEntry = {
|
|
82
|
+
id: string;
|
|
83
|
+
name: string;
|
|
84
|
+
materializedAt: string;
|
|
85
|
+
url?: string;
|
|
86
|
+
docToken?: string;
|
|
87
|
+
wikiToken?: string;
|
|
88
|
+
title?: string;
|
|
89
|
+
snapshot?: {
|
|
90
|
+
manifest: string;
|
|
91
|
+
};
|
|
92
|
+
};
|
|
93
|
+
export type RepoSourcesRegistry = {
|
|
94
|
+
kind: "sources.registry.repo";
|
|
95
|
+
registryPath: string;
|
|
96
|
+
absolutePath: string;
|
|
97
|
+
repos: readonly RepoSourceRegistryEntry[];
|
|
98
|
+
};
|
|
99
|
+
export type SourcesRegistry = {
|
|
100
|
+
kind: "sources.registry";
|
|
101
|
+
registryPaths: {
|
|
102
|
+
repo: string;
|
|
103
|
+
file: string;
|
|
104
|
+
lark: string;
|
|
105
|
+
};
|
|
106
|
+
absolutePaths: {
|
|
107
|
+
repo: string;
|
|
108
|
+
file: string;
|
|
109
|
+
lark: string;
|
|
110
|
+
};
|
|
111
|
+
repos: readonly RepoSourceRegistryEntry[];
|
|
112
|
+
files: readonly FileSourceRegistryEntry[];
|
|
113
|
+
larks: readonly LarkSourceRegistryEntry[];
|
|
114
|
+
};
|
|
115
|
+
export type LoadSourcesRegistryOptions = {
|
|
116
|
+
rootDir?: string;
|
|
117
|
+
registryPath?: string;
|
|
118
|
+
repoRegistryPath?: string;
|
|
119
|
+
fileRegistryPath?: string;
|
|
120
|
+
larkRegistryPath?: string;
|
|
121
|
+
};
|
|
122
|
+
export type SourceDefinition = RepoSourceDefinition | FileSourceDefinition | LarkSourceDefinition | RegistrySourceReference | SourceReference;
|
|
123
|
+
export type DocumentSourceDefinition = FileSourceDefinition | LarkSourceDefinition | DocumentSourceReference;
|
|
124
|
+
export type RepoProjectSourceDefinition = RepoSourceDefinition | RepoSourceReference | SourceCollectionReference<"repo">;
|
|
125
|
+
export type ProjectSourceDefinition = SourceDefinition | SourceCollectionReference;
|
|
126
|
+
export declare function source(name: string): RegistrySourceReference;
|
|
127
|
+
export declare function source(name: string, options: {
|
|
128
|
+
type: "repo";
|
|
129
|
+
}): RepoSourceReference;
|
|
130
|
+
export declare function source(name: string, options: {
|
|
131
|
+
type: "file";
|
|
132
|
+
}): FileSourceReference;
|
|
133
|
+
export declare function source(name: string, options: {
|
|
134
|
+
type: "lark";
|
|
135
|
+
}): LarkSourceReference;
|
|
136
|
+
export declare const loadSourcesRegistry: (options?: LoadSourcesRegistryOptions) => Promise<SourcesRegistry>;
|
|
137
|
+
export declare const resolveSourceReference: (reference: RepoSourceDefinition | RepoSourceReference, registry: Pick<SourcesRegistry, "repos" | "registryPaths">) => RepoSourceDefinition;
|
|
138
|
+
export declare const allSources: <TType extends SourceType>(type: TType) => readonly [SourceCollectionReference<TType>];
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# {{displayName}}
|
|
2
|
+
|
|
3
|
+
This package was generated from a Context knowledge workspace.
|
|
4
|
+
|
|
5
|
+
Package: `{{packageName}}`
|
|
6
|
+
Kind: `{{packageKind}}`
|
|
7
|
+
Approved knowledge files: `{{knowledgeCount}}`
|
|
8
|
+
|
|
9
|
+
## How To Use
|
|
10
|
+
|
|
11
|
+
Use the Markdown files in this package as source-linked product and code
|
|
12
|
+
knowledge. Prefer cited facts from the included knowledge pages over memory.
|
|
13
|
+
|
|
14
|
+
The `skills/knowledge-query/SKILL.md` entry teaches agents how to navigate OKF
|
|
15
|
+
indexes and cite copied OKF root directories, starting with
|
|
16
|
+
`wikis/`. Customize template files before build when the package needs
|
|
17
|
+
product-specific skills or routing rules.
|
|
18
|
+
|
|
19
|
+
Selected OKF root directories such as `wikis/`, `guides/`, `rules/`, and
|
|
20
|
+
`feats/` follow the C4A OKF Profile: OKF fields and C4A extension fields stay
|
|
21
|
+
at the top level, and no `context` or `schema` field is emitted. Root mapping:
|
|
22
|
+
`wikis/` maps from internal `codegraph`, `business`, `architecture`, `faq`, and
|
|
23
|
+
`decision`; `guides/` maps from `sop` and `incident`; `rules/` maps from
|
|
24
|
+
`product`, `standards`, and `test`; `feats/` maps from `feats`. Customize
|
|
25
|
+
`wikis/index.md` before build to describe the package scope and query guidance;
|
|
26
|
+
other selected OKF root indexes are generated unless this template supplies
|
|
27
|
+
them.
|
|
28
|
+
|
|
29
|
+
## Included Knowledge
|
|
30
|
+
|
|
31
|
+
The approved Markdown files are copied into this package during `context build`.
|
|
@@ -0,0 +1,204 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: knowledge-query
|
|
3
|
+
description: Query the approved knowledge bundled with {{displayName}}.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Knowledge Query
|
|
7
|
+
|
|
8
|
+
Use this starter skill when the user asks about APIs, components, usage patterns,
|
|
9
|
+
migration details, relationships, or source-linked facts covered by this
|
|
10
|
+
package. Customize it before build if the package needs project-specific
|
|
11
|
+
routing, terminology, or task workflows.
|
|
12
|
+
|
|
13
|
+
## Non-negotiables
|
|
14
|
+
|
|
15
|
+
- Structure first: start from OKF indexes and package structure before opening
|
|
16
|
+
individual pages.
|
|
17
|
+
- Bundled knowledge pages are evidence cards. Do not answer from memory when a
|
|
18
|
+
copied page exists.
|
|
19
|
+
- Cite every substantive claim with a page path and, when available, a
|
|
20
|
+
`context:section` id/source_ref.
|
|
21
|
+
- Frontmatter summaries help route the query; reader-visible section content is
|
|
22
|
+
the evidence for factual answers.
|
|
23
|
+
- If the package does not contain evidence for the requested fact, report a gap
|
|
24
|
+
instead of inferring from adjacent pages.
|
|
25
|
+
- Do not treat direct grep over bundled OKF root directories as the primary
|
|
26
|
+
discovery path. Use it only as a fallback after indexes and page structure do
|
|
27
|
+
not identify a scope.
|
|
28
|
+
|
|
29
|
+
## Evidence Shape
|
|
30
|
+
|
|
31
|
+
Treat each opened knowledge page or package artifact as an evidence card:
|
|
32
|
+
|
|
33
|
+
| Evidence field | Use |
|
|
34
|
+
|---|---|
|
|
35
|
+
| Page path | Citation handle and package-local identity. |
|
|
36
|
+
| Frontmatter `title` / `description` / `node_type` / `tags` | Navigation and scope selection; not enough by itself for factual claims. |
|
|
37
|
+
| `context:section` id / kind / source_ref metadata | Section citation handle and evidence boundary. |
|
|
38
|
+
| Reader-visible section body | Primary evidence for factual answers. |
|
|
39
|
+
| `context-build-inventory.json` `structure.edge_records` | Package-visible relationship evidence when typed edges are selected into this package. |
|
|
40
|
+
| `context-build-inventory.json` | Package scope, counts, selected-by reasons, edge records, and build-time visibility evidence. |
|
|
41
|
+
|
|
42
|
+
Frontmatter and indexes orient the search; reader-visible section content and
|
|
43
|
+
source-backed edge records support claims. If a source_ref points to evidence
|
|
44
|
+
that is not bundled, cite the approved knowledge section that reviewed it and avoid expanding
|
|
45
|
+
beyond the packaged content.
|
|
46
|
+
|
|
47
|
+
## Route By Intent
|
|
48
|
+
|
|
49
|
+
| User intent | First move | Evidence move |
|
|
50
|
+
|---|---|---|
|
|
51
|
+
| Vague topic or unknown name | Open the package's OKF root index, usually `wikis/index.md`, then child indexes such as `wikis/<group>/index.md`. If the package includes other selected OKF roots such as `guides/` or `rules/`, use their indexes too. | Choose candidate pages by title, path, frontmatter, and index grouping. |
|
|
52
|
+
| Process, runbook, SOP, incident, oncall, or troubleshooting question | Start from `guides/index.md` when present. These pages are mapped from internal `sop` and `incident` collections. | Use guide pages for steps, roles, operational context, incident timelines, and action items; cite sections rather than general procedure memory. |
|
|
53
|
+
| Requirement, PRD, standard, spec, acceptance, or test scenario question | Start from `rules/index.md` when present. These pages are mapped from internal `product`, `standards`, and `test` collections. | Use rule pages for requirements, constraints, acceptance criteria, validation scenarios, and normative decisions. |
|
|
54
|
+
| Specific entity/domain/action named | Open the matching page or nearest group index. | Read the page sections and source metadata. |
|
|
55
|
+
| Relationship or impact question | Check `context-build-inventory.json` `structure.edge_records`, then related endpoint pages. | Cite typed edge evidence if available; otherwise cite page sections and mark relation gaps. |
|
|
56
|
+
| Detail within a known page | Read that page's relevant `context:section` block. | Cite the section id/source_ref and quote or summarize only supported text. |
|
|
57
|
+
| Coverage, gaps, or package scope | Check indexes and `context-build-inventory.json`. | Cite those package artifacts plus relevant pages. |
|
|
58
|
+
|
|
59
|
+
Classify the user's question before opening pages. Structure queries take
|
|
60
|
+
priority over keyword search:
|
|
61
|
+
|
|
62
|
+
- Vague problem: show the relevant package structure first, then choose or ask
|
|
63
|
+
for a page/group scope. Do not answer from a package-wide text hit before
|
|
64
|
+
choosing the likely Node/page.
|
|
65
|
+
- Explicit Node/page name: open the matching page or nearest group index. If
|
|
66
|
+
several pages normalize to the same name, show the candidates instead of
|
|
67
|
+
guessing.
|
|
68
|
+
- Relationship/impact: inspect typed edges first, then read both endpoint
|
|
69
|
+
pages. If an edge is absent, page co-occurrence is not relationship evidence.
|
|
70
|
+
- Detail inside a chosen scope: open only the relevant page sections. Use
|
|
71
|
+
search only to locate the section inside that page or group.
|
|
72
|
+
- Coverage/gap/audit: use package artifacts first, then supporting pages.
|
|
73
|
+
|
|
74
|
+
If the package structure returns multiple plausible pages, ask the user to pick
|
|
75
|
+
or state the selection basis before answering. If no page or edge supports the
|
|
76
|
+
requested fact, report a gap; do not broaden search until something vaguely
|
|
77
|
+
matches.
|
|
78
|
+
|
|
79
|
+
## Workflow
|
|
80
|
+
|
|
81
|
+
1. Start with the relevant OKF root index, usually `wikis/index.md`, to
|
|
82
|
+
understand the package scope.
|
|
83
|
+
2. Follow OKF directory indexes such as `wikis/<group>/index.md` before opening
|
|
84
|
+
pages. If the package includes other selected OKF roots, inspect their
|
|
85
|
+
indexes the same way.
|
|
86
|
+
3. Open only the candidate pages needed for the question; avoid workspace-wide
|
|
87
|
+
reading unless the user asks for an inventory.
|
|
88
|
+
4. Inspect frontmatter `node_type`, `sources`, and `context:section` comments to
|
|
89
|
+
confirm evidence boundaries.
|
|
90
|
+
5. Answer from reader-visible section content. Use source_ref metadata as
|
|
91
|
+
citation and freshness context, not as a license to invent missing facts.
|
|
92
|
+
6. Cite source-linked facts from the knowledge page when the answer depends on
|
|
93
|
+
code or reviewed knowledge.
|
|
94
|
+
7. If the indexes and matching pages do not cover the request, return a
|
|
95
|
+
structured gap: requested topic, indexes/pages checked, and missing source
|
|
96
|
+
span or source_ref.
|
|
97
|
+
|
|
98
|
+
For follow-up exploration, stay within the package boundary:
|
|
99
|
+
|
|
100
|
+
- User asks about dependencies or impact: inspect `context-build-inventory.json`
|
|
101
|
+
`structure.edge_records` and the endpoint pages.
|
|
102
|
+
- User asks for full detail after a partial answer: continue within the same
|
|
103
|
+
page or its child index before expanding outward.
|
|
104
|
+
- User asks for a specific feature or behavior: use exact terminology,
|
|
105
|
+
bilingual terms, product aliases, API names, flags, and error strings from the
|
|
106
|
+
question to locate a section, then answer from the section body.
|
|
107
|
+
- User mentions another page through a referenced edge or section link: open it
|
|
108
|
+
only if the relationship question requires it or the user asks to drill down.
|
|
109
|
+
- Do not auto-open every related page, edge endpoint, or search hit just because
|
|
110
|
+
it is present.
|
|
111
|
+
|
|
112
|
+
## Search Fallback
|
|
113
|
+
|
|
114
|
+
Use text search only after the structure path above fails to identify a scope.
|
|
115
|
+
|
|
116
|
+
- Search with exact product names, API names, bilingual terms, aliases, and
|
|
117
|
+
error strings from the user's question.
|
|
118
|
+
- Prefer scoped search under a likely group/page over a package-wide scan.
|
|
119
|
+
- A search hit is only a lead. Open the containing page/section and answer from
|
|
120
|
+
the section body, not from the hit line alone.
|
|
121
|
+
- If search returns only unrelated pages, report the gap instead of broadening
|
|
122
|
+
until something vaguely matches.
|
|
123
|
+
|
|
124
|
+
Search is keyword-literal, so use deliberate terms:
|
|
125
|
+
|
|
126
|
+
- mix Chinese and English names when both may appear in the package;
|
|
127
|
+
- include version numbers, API names, config keys, command flags, and exact
|
|
128
|
+
error strings when the user provides them;
|
|
129
|
+
- try aliases and synonyms only to locate a candidate page, not to justify a
|
|
130
|
+
claim;
|
|
131
|
+
- after a search hit, return to structure: identify the page, section, and
|
|
132
|
+
evidence boundary before answering.
|
|
133
|
+
|
|
134
|
+
Do not use search for relationship or impact claims when a typed edge is
|
|
135
|
+
available. Relationship answers should cite the edge first; search can only
|
|
136
|
+
find endpoint details.
|
|
137
|
+
|
|
138
|
+
## Citation Shape
|
|
139
|
+
|
|
140
|
+
Use compact citations keyed to package artifacts:
|
|
141
|
+
|
|
142
|
+
```text
|
|
143
|
+
Page identity/title: <claim> [<okf-root>/path/page.md]
|
|
144
|
+
Section claim: <claim> [<okf-root>/path/page.md#section-id]
|
|
145
|
+
Source-backed detail: <claim> [<okf-root>/path/page.md#section-id, source_ref]
|
|
146
|
+
Relationship/edge: <claim> [context-build-inventory.json#structure.edge_records edge:<type>]
|
|
147
|
+
Package coverage/gap: <claim> [context-build-inventory.json]
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
If several sections support the same claim, cite the strongest one or two and
|
|
151
|
+
explain what each supports. Do not list citations without tying them to claims.
|
|
152
|
+
|
|
153
|
+
For relationship answers, cite the typed edge when present and then cite endpoint
|
|
154
|
+
sections for the facts about each endpoint. If no edge exists, do not infer a relationship from co-occurrence; say that the package lacks a source-backed relationship edge and cite any weaker page-level evidence separately.
|
|
155
|
+
|
|
156
|
+
Use citation scope conservatively:
|
|
157
|
+
|
|
158
|
+
- Page identity/title claims can cite the page path.
|
|
159
|
+
- Factual behavior, constraints, examples, warnings, and usage claims need a
|
|
160
|
+
`context:section` citation when available.
|
|
161
|
+
- Package coverage or known-limit claims need `context-build-inventory.json`
|
|
162
|
+
and/or the checked indexes/pages.
|
|
163
|
+
- `source_ref` metadata names the reviewed evidence boundary, but the source
|
|
164
|
+
body may not be bundled. Do not invent source text that is not present in the
|
|
165
|
+
packaged knowledge page.
|
|
166
|
+
|
|
167
|
+
## Gap Shape
|
|
168
|
+
|
|
169
|
+
When the package lacks evidence, say so explicitly:
|
|
170
|
+
|
|
171
|
+
```text
|
|
172
|
+
Gap: this package did not return evidence for <missing point>.
|
|
173
|
+
Checked: <indexes/pages/artifacts>.
|
|
174
|
+
Next useful source need: <source, page, or source_ref if known>.
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Do not fill the gap from general product knowledge, previous conversations, or
|
|
178
|
+
raw source files outside this package.
|
|
179
|
+
|
|
180
|
+
If the likely cause is that source material was captured but not approved into
|
|
181
|
+
this package, say that the packaged knowledge does not include it. Do not tell
|
|
182
|
+
the user it is false; distinguish "not evidenced here" from "not true."
|
|
183
|
+
|
|
184
|
+
## Knowledge Boundary
|
|
185
|
+
|
|
186
|
+
- The bundled OKF root directories, usually including `wikis/`, are the source
|
|
187
|
+
of truth for this skill.
|
|
188
|
+
- OKF root mapping: `wikis/` maps from internal `codegraph`, `business`,
|
|
189
|
+
`architecture`, `faq`, and `decision`; `guides/` maps from `sop` and
|
|
190
|
+
`incident`; `rules/` maps from `product`, `standards`, and `test`; `feats/`
|
|
191
|
+
maps from `feats`.
|
|
192
|
+
- Bundled OKF root directories follow the C4A OKF Profile.
|
|
193
|
+
- Prefer OKF indexes, `context-build-inventory.json`, package manifests when
|
|
194
|
+
present, build inventory, and page source span metadata over raw text search.
|
|
195
|
+
- Do not rely on memory when a knowledge page exists.
|
|
196
|
+
- Do not claim the package is complete; it only contains approved knowledge that
|
|
197
|
+
was selected by the Context workspace.
|
|
198
|
+
- If the package lacks project-specific instructions, state that the default
|
|
199
|
+
skill is a generic query entry and report gaps instead of inventing workflow
|
|
200
|
+
guidance.
|
|
201
|
+
|
|
202
|
+
## Included Knowledge
|
|
203
|
+
|
|
204
|
+
Approved knowledge files: `{{knowledgeCount}}`
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
type: Knowledge Bundle
|
|
3
|
+
title: "{{displayName}}"
|
|
4
|
+
description: "Approved knowledge bundle generated from a Context workspace."
|
|
5
|
+
tags:
|
|
6
|
+
- context
|
|
7
|
+
- knowledge-base
|
|
8
|
+
timestamp: "{{knowledgeTimestamp}}"
|
|
9
|
+
resource: "context://package/{{packageName}}/wikis"
|
|
10
|
+
package: "{{packageName}}"
|
|
11
|
+
package_kind: "{{packageKind}}"
|
|
12
|
+
knowledge_count: {{knowledgeCount}}
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
<!-- context:template
|
|
16
|
+
This file is a starter template. It is rendered by `context build` and copied to
|
|
17
|
+
`dist/<package-name>/wikis/index.md`.
|
|
18
|
+
|
|
19
|
+
Template comments that start with `context:template` are removed from build output.
|
|
20
|
+
Read the template variable guide before customizing:
|
|
21
|
+
node_modules/@c4a/context/docs/reference/template-variables.md
|
|
22
|
+
|
|
23
|
+
Customize this file before calling the package usable. Add the bundle scope,
|
|
24
|
+
intended readers, recommended reading order, known gaps, product scenarios,
|
|
25
|
+
or task-focused entry sections. The default root index lists only the
|
|
26
|
+
next-level directories; context build generates directory-level index.md
|
|
27
|
+
files below it.
|
|
28
|
+
-->
|
|
29
|
+
|
|
30
|
+
# {{displayName}}
|
|
31
|
+
|
|
32
|
+
This knowledge bundle contains `{{knowledgeCount}}` approved knowledge page(s).
|
|
33
|
+
Use this index as the entry point, then open the linked knowledge pages for source-linked details.
|
|
34
|
+
|
|
35
|
+
## Contents
|
|
36
|
+
|
|
37
|
+
{{knowledgeGroupsMarkdown}}
|
|
38
|
+
|
|
39
|
+
## How To Use
|
|
40
|
+
|
|
41
|
+
- Start from the directory list above, then open child indexes and linked knowledge pages for source-linked details.
|
|
42
|
+
- Use `skills/knowledge-query/SKILL.md` when this bundle is installed as an agent knowledge package.
|
|
43
|
+
- Customize `src/package-templates/kb/wikis/index.md` before build to add bundle scope, known gaps, project-specific reading paths, or task entry points.
|